/ Hex Artifact Content
Login

Artifact 16c6ed1b8e7a2bcdff41306f5115cbe5ed0c8c23:


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 32 38 38 20 32 30 30 38 2f  in,v 1.288 2008/
05f0: 30 33 2f 30 31 20 32 33 3a 33 34 3a 34 37 20 6d  03/01 23:34:47 m
0600: 6c 63 72 65 65 63 68 20 45 78 70 20 24 0a 2a 2f  lcreech 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 4d 61 6b 65 20 73  if../*.** Make s
0750: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0760: 73 20 77 68 65 72 65 20 6e 6f 74 20 64 65 66 69  s where not defi
0770: 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76  ned by some prev
0780: 69 6f 75 73 20 68 65 61 64 65 72 0a 2a 2a 20 66  ious header.** f
0790: 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ile..*/.#ifdef S
07a0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20  QLITE_VERSION.# 
07b0: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  undef SQLITE_VER
07c0: 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64  SION.#endif.#ifd
07d0: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
07e0: 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66  N_NUMBER.# undef
07f0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0800: 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f  NUMBER.#endif../
0810: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
0820: 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72  ompile-Time Libr
0830: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
0840: 65 72 73 20 7b 46 31 30 30 31 30 7d 0a 2a 2a 0a  ers {F10010}.**.
0850: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  ** The SQLITE_VE
0860: 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45  RSION and SQLITE
0870: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0880: 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74  #defines in.** t
0890: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c  he sqlite3.h fil
08a0: 65 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65  e specify the ve
08b0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
08c0: 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68  with which.** th
08d0: 61 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69  at header file i
08e0: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a  s associated..**
08f0: 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e  .** The "version
0900: 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61  " of SQLite is a
0910: 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66   string of the f
0920: 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20  orm "X.Y.Z"..** 
0930: 54 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68  The phrase "alph
0940: 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67  a" or "beta" mig
0950: 68 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61  ht be appended a
0960: 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54  fter the Z..** T
0970: 68 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61  he X value is ma
0980: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0990: 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53  er always 3 in S
09a0: 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58  QLite3..** The X
09b0: 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e   value only chan
09c0: 67 65 73 20 77 68 65 6e 20 20 62 61 63 6b 77 61  ges when  backwa
09d0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
09e0: 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61  y is.** broken a
09f0: 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20  nd we intend to 
0a00: 6e 65 76 65 72 20 62 72 65 61 6b 0a 2a 2a 20 62  never break.** b
0a10: 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
0a20: 62 69 6c 69 74 79 2e 20 20 54 68 65 20 59 20 76  bility.  The Y v
0a30: 61 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f  alue is the mino
0a40: 72 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 6e 75 6d  r version.** num
0a50: 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63 68 61  ber and only cha
0a60: 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nges when.** the
0a70: 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 66 65 61  re are major fea
0a80: 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65 6e 74  ture enhancement
0a90: 73 20 74 68 61 74 20 61 72 65 20 66 6f 72 77 61  s that are forwa
0aa0: 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 0a 2a  rds compatible.*
0ab0: 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 6b 77 61  * but not backwa
0ac0: 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65 2e 20  rds compatible. 
0ad0: 20 54 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20   The Z value is 
0ae0: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 0a 2a  release number.*
0af0: 2a 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65  * and is increme
0b00: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63  nted with.** eac
0b10: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65  h release but re
0b20: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77  sets back to 0 w
0b30: 68 65 6e 20 59 20 69 73 20 69 6e 63 72 65 6d 65  hen Y is increme
0b40: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nted..**.** See 
0b50: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
0b60: 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  ibversion()] and
0b70: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b80: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a  sion_number()]..
0b90: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
0ba0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 31 31 7d  :.**.** {F10011}
0bb0: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0bc0: 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74  ION #define in t
0bd0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0be0: 64 65 72 20 66 69 6c 65 0a 2a 2a 20 20 20 20 20  der file.**     
0bf0: 20 20 20 20 20 65 76 61 6c 75 61 74 65 73 20 74       evaluates t
0c00: 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
0c10: 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53  al that is the S
0c20: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 0a 2a 2a  QLite version.**
0c30: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 77            with w
0c40: 68 69 63 68 20 74 68 65 20 68 65 61 64 65 72 20  hich the header 
0c50: 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74  file is associat
0c60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 31  ed..**.** {F1001
0c70: 34 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  4} The SQLITE_VE
0c80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65  RSION_NUMBER #de
0c90: 66 69 6e 65 20 72 65 73 6f 6c 76 65 73 20 74 6f  fine resolves to
0ca0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
0cb0: 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
0cc0: 20 76 61 6c 75 65 20 20 28 58 2a 31 30 30 30 30   value  (X*10000
0cd0: 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29  00 + Y*1000 + Z)
0ce0: 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64   where X, Y, and
0cf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 20 61  .**          Z a
0d00: 72 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72  re the major ver
0d10: 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73  sion, minor vers
0d20: 69 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65  ion, and release
0d30: 20 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64 65 66   number..*/.#def
0d40: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
0d50: 4f 4e 20 20 20 20 20 20 20 20 20 22 2d 2d 56 45  ON         "--VE
0d60: 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51  RS--".#define SQ
0d70: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0d80: 42 45 52 20 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e  BER  --VERSION-N
0d90: 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43  UMBER--../*.** C
0da0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
0db0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0dc0: 6e 20 4e 75 6d 62 65 72 73 20 7b 46 31 30 30 32  n Numbers {F1002
0dd0: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
0de0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a  sqlite3_version.
0df0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74  **.** These feat
0e00: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  ures provide the
0e10: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0e20: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
0e30: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64  _VERSION].** and
0e40: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e50: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65  _NUMBER] #define
0e60: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c  s in the header,
0e70: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
0e80: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
0e90: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
0ea0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
0eb0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72  le.  Cautious pr
0ec0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a  ogrammers might.
0ed0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65  ** include a che
0ee0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ck in their appl
0ef0: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66  ication to verif
0f00: 79 20 74 68 61 74 20 0a 2a 2a 20 73 71 6c 69 74  y that .** sqlit
0f10: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f20: 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65  mber() always re
0f30: 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
0f40: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
0f50: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a  ION_NUMBER]..**.
0f60: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  ** The sqlite3_l
0f70: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
0f80: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
0f90: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0fa0: 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68  n as is.** in th
0fb0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
0fc0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
0fd0: 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  ant.  The functi
0fe0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a  on is provided.*
0ff0: 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  * for use in DLL
1000: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
1010: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1020: 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63 63   have direct acc
1030: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a  ess to string.**
1040: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1050: 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a  n the DLL..**.**
1060: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1070: 2a 2a 20 7b 46 31 30 30 32 31 7d 20 54 68 65 20  ** {F10021} The 
1080: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
1090: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e  ion_number()] in
10a0: 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
10b0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
10c0: 20 20 20 20 20 20 20 65 71 75 61 6c 20 74 6f 20         equal to 
10d0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
10e0: 4e 55 4d 42 45 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20  NUMBER]. .**.** 
10f0: 7b 46 31 30 30 32 32 7d 20 54 68 65 20 5b 73 71  {F10022} The [sq
1100: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73  lite3_version] s
1110: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
1120: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
1130: 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
1140: 20 20 20 20 5b 53 51 4c 49 54 45 5f 56 45 52 53      [SQLITE_VERS
1150: 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20 0a 2a 2a  ION] string. .**
1160: 0a 2a 2a 20 7b 46 31 30 30 32 33 7d 20 54 68 65  .** {F10023} The
1170: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1180: 73 69 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e  sion()] function
1190: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
11a0: 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
11b0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
11c0: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63  ersion] string c
11d0: 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49  onstant..*/.SQLI
11e0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
11f0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
1200: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
1210: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
1220: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1230: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1240: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1260: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1270: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1280: 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 46 31  s Threadsafe {F1
1290: 30 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  0100}.**.** SQLi
12a0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
12b0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
12c0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
12d0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  n.** the SQLITE_
12e0: 54 48 52 45 41 44 53 41 46 45 20 43 20 70 72 65  THREADSAFE C pre
12f0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1300: 69 73 20 74 72 75 65 2c 20 6d 75 74 65 78 65 73  is true, mutexes
1310: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1320: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1330: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1340: 74 68 61 74 20 6d 61 63 72 6f 20 6f 73 20 66 61  that macro os fa
1350: 6c 73 65 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lse,.** the mute
1360: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
1370: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
1380: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
1390: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
13a0: 53 51 4c 69 74 65 20 66 72 6f 6d 20 6d 6f 72 65  SQLite from more
13b0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
13c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 69 73  ..**.** There is
13d0: 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65   a measurable pe
13e0: 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74  rformance penalt
13f0: 79 20 66 6f 72 20 65 6e 61 62 6c 69 6e 67 20 6d  y for enabling m
1400: 75 74 65 78 65 73 2e 0a 2a 2a 20 53 6f 20 69 66  utexes..** So if
1410: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1420: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1430: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1440: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1450: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1460: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1470: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1480: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1490: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68   The default beh
14a0: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
14b0: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
14c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
14d0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
14e0: 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61  used by a progra
14f0: 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  m to make sure t
1500: 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69  hat the.** versi
1510: 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61  on of SQLite tha
1520: 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20  t it is linking 
1530: 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70  against was comp
1540: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
1550: 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67   desired setting
1560: 20 6f 66 20 74 68 65 20 53 51 4c 49 54 45 5f 54   of the SQLITE_T
1570: 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 2e  HREADSAFE macro.
1580: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1590: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31  S:.**.** {F10101
15a0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
15b0: 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75 6e  hreadsafe()] fun
15c0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
15d0: 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20  nzero if.**     
15e0: 20 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 20       SQLite was 
15f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 69 74  compiled with it
1600: 73 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65  s mutexes enable
1610: 64 20 6f 72 20 7a 65 72 6f 0a 2a 2a 20 20 20 20  d or zero.**    
1620: 20 20 20 20 20 20 69 66 20 53 51 4c 69 74 65 20        if SQLite 
1630: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1640: 68 20 6d 75 74 65 78 65 73 20 64 69 73 61 62 6c  h mutexes disabl
1650: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
1660: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
1670: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1680: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
1690: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
16a0: 20 7b 46 31 32 30 30 30 7d 0a 2a 2a 20 4b 45 59   {F12000}.** KEY
16b0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
16c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 0a 2a 2a 0a   connection}.**.
16d0: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
16e0: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
16f0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 70  represented by p
1700: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1710: 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a 2a 20  tance of the.** 
1720: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1730: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1740: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1750: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1760: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1770: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1780: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1790: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
17a0: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
17b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
17c0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
17d0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
17e0: 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b 73 71  ctors.** and [sq
17f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
1800: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
1810: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
1820: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
1830: 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73 20 5b  es.** (such as [
1840: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1850: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
1860: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
1870: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1880: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1890: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
18a0: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
18b0: 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69 73 0a  methods on this.
18c0: 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  ** object..*/.ty
18d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
18e0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 0a  ite3 sqlite3;...
18f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1900: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
1910: 79 70 65 73 20 7b 46 31 30 32 30 30 7d 0a 2a 2a  ypes {F10200}.**
1920: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
1930: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
1940: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
1950: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
1960: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
1970: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
1980: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
1990: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
19a0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
19b0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
19c0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
19d0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
19e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
19f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
1a00: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
1a10: 72 72 65 64 20 74 79 70 65 0a 2a 2a 20 64 65 66  rred type.** def
1a20: 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68 65 20 73  initions.  The s
1a30: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20  qlite_int64 and 
1a40: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
1a50: 70 65 73 20 61 72 65 0a 2a 2a 20 73 75 70 70 6f  pes are.** suppo
1a60: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
1a70: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1a80: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   only..**.** INV
1a90: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1aa0: 46 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c  F10201} The [sql
1ab0: 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b  ite_int64] and [
1ac0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74  sqlite3_int64] t
1ad0: 79 70 65 73 20 73 70 65 63 69 66 79 20 61 0a 2a  ypes specify a.*
1ae0: 2a 20 20 20 20 20 20 20 20 20 20 36 34 2d 62 69  *          64-bi
1af0: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1b00: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 32 7d  ..**.** {F10202}
1b10: 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75 69 6e   The [sqlite_uin
1b20: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1b30: 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65 73 20  3_uint64] types 
1b40: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1b50: 20 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73      a 64-bit uns
1b60: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1b70: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1b80: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
1b90: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
1ba0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
1bb0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
1bc0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
1bd0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1be0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
1bf0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
1c00: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
1c10: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
1c20: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
1c30: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1c40: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
1c50: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
1c60: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
1c70: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
1c80: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
1c90: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
1ca0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
1cb0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
1cc0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
1cd0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
1ce0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
1cf0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
1d00: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
1d10: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
1d20: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
1d30: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
1d40: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
1d50: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
1d60: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
1d70: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
1d80: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1d90: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f  E_OMIT_FLOATING_
1da0: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64  POINT.# define d
1db0: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e  ouble sqlite3_in
1dc0: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  t64.#endif../*.*
1dd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
1de0: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43  ing A Database C
1df0: 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 30 31  onnection {F1201
1e00: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
1e10: 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73  utine is the des
1e20: 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
1e30: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1e40: 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  .  .**.** Applic
1e50: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
1e60: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
1e70: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 0a  | finalize] all.
1e80: 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1e90: 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a 2a 2a 20  tements] and.** 
1ea0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
1eb0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
1ec0: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
1ed0: 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61 73 73 6f   BLOBs] .** asso
1ee0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1ef0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f00: 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 61 74 74   prior.** to att
1f10: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
1f20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1f30: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 3c 74 6f  bject..**.** <to
1f40: 64 6f 3e 57 68 61 74 20 68 61 70 70 65 6e 73 20  do>What happens 
1f50: 74 6f 20 70 65 6e 64 69 6e 67 20 74 72 61 6e 73  to pending trans
1f60: 61 63 74 69 6f 6e 73 3f 20 20 41 72 65 20 74 68  actions?  Are th
1f70: 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  ey.** rolled bac
1f80: 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e 65 64 3f  k, or abandoned?
1f90: 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e  </todo>.**.** IN
1fa0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1fb0: 7b 46 31 32 30 31 31 7d 20 54 68 65 20 5b 73 71  {F12011} The [sq
1fc0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
1fd0: 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
1fe0: 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  s an [sqlite3] o
1ff0: 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20  bject.**        
2000: 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61    allocated by a
2010: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
2020: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2030: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2040: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2050: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
2060: 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  n_v2()]..**.** {
2070: 46 31 32 30 31 32 7d 20 54 68 65 20 5b 73 71 6c  F12012} The [sql
2080: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 66 75  ite3_close()] fu
2090: 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73 65 73 20  nction releases 
20a0: 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73 65 64 20  all memory used 
20b0: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
20c0: 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e     connection an
20d0: 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20 6f 70 65  d closes all ope
20e0: 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  n files..**.** {
20f0: 46 31 32 30 31 33 7d 20 49 66 20 74 68 65 20 64  F12013} If the d
2100: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2110: 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  on contains.**  
2120: 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2130: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 74 68  d statements] th
2140: 61 74 20 68 61 76 65 20 6e 6f 74 20 62 65 65 6e  at have not been
2150: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6e  .**          fin
2160: 61 6c 69 7a 65 64 20 62 79 20 5b 73 71 6c 69 74  alized by [sqlit
2170: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 20  e3_finalize()], 
2180: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c  then [sqlite3_cl
2190: 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ose()].**       
21a0: 20 20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49     returns [SQLI
21b0: 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 6c 65 61  TE_BUSY] and lea
21c0: 76 65 73 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ves the connecti
21d0: 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  on open..**.** {
21e0: 46 31 32 30 31 34 7d 20 47 69 76 69 6e 67 20 73  F12014} Giving s
21f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2200: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2210: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
2220: 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  p..**.** LIMITAT
2230: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
2240: 30 31 35 7d 20 54 68 65 20 70 61 72 61 6d 65 74  015} The paramet
2250: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2260: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lose()] must be 
2270: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2280: 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ect.**          
2290: 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
22a0: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
22b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
22c0: 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20  ] or the .**    
22d0: 20 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74        equivalent
22e0: 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
22f0: 20 7b 55 31 32 30 31 36 7d 20 54 68 65 20 70 61   {U12016} The pa
2300: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2310: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73  te3_close()] mus
2320: 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
2330: 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
2340: 20 20 20 20 20 20 20 63 6c 6f 73 65 64 2e 0a 2a         closed..*
2350: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2360: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
2370: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
2380: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
2390: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
23a0: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
23b0: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
23c0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
23d0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
23e0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
23f0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
2400: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
2410: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
2420: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
2430: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
2440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2450: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
2460: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
2470: 61 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a 2a 0a  ace {F12100}.**.
2480: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
24a0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20  is a convenient 
24b0: 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 0a 2a  way of running.*
24c0: 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 53 51  * one or more SQ
24d0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74  L statements wit
24e0: 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66 20 43 20  hout a lot of C 
24f0: 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a 20 53 51  code.  The.** SQ
2500: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
2510: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2520: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2530: 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
2540: 5f 65 78 65 63 28 29 2e 20 20 54 68 65 20 73 74  _exec().  The st
2550: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
2560: 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e  luated one by on
2570: 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69 74 68 65  e.** until eithe
2580: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  r an error or an
2590: 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e   interrupt is en
25a0: 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a 2a 2a 20  countered or.** 
25b0: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61  until they are a
25c0: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72  ll done.  The 3r
25d0: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
25e0: 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a 20 63 61  n optional.** ca
25f0: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69  llback that is i
2600: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2610: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20  each row of any 
2620: 71 75 65 72 79 20 72 65 73 75 6c 74 73 0a 2a 2a  query results.**
2630: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65   produced by the
2640: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
2650: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
2660: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a  ter tells where.
2670: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20  ** to write any 
2680: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a  error messages..
2690: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26a0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
26b0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
26c0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
26d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
26f0: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
2700: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2710: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
2720: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
2730: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
2740: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
2750: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
2760: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2770: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2780: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2790: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
27a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
27b0: 63 28 29 20 69 73 20 6a 75 73 74 20 61 20 63 6f  c() is just a co
27c0: 6e 76 65 6e 69 65 6e 74 20 77 72 61 70 70 65 72  nvenient wrapper
27d0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
27e0: 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 31  TS:.** .** {F121
27f0: 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
2800: 5f 65 78 65 63 28 29 5d 20 69 6e 74 65 72 66 61  _exec()] interfa
2810: 63 65 20 65 76 61 6c 75 61 74 65 73 20 7a 65 72  ce evaluates zer
2820: 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 0a  o or more UTF-8.
2830: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f  **          enco
2840: 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ded, semicolon-s
2850: 65 70 61 72 61 74 65 64 2c 20 53 51 4c 20 73 74  eparated, SQL st
2860: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 0a  atements in the.
2870: 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2880: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
2890: 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
28a0: 72 61 6d 65 74 65 72 20 77 69 74 68 69 6e 20 74  rameter within t
28b0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
28c0: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 73  ontext of the [s
28d0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 67  qlite3] object g
28e0: 69 76 65 6e 20 69 6e 20 74 68 65 20 31 73 74 20  iven in the 1st 
28f0: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2900: 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20 72 65   {F12104} The re
2910: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
2920: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
2930: 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  s SQLITE_OK if a
2940: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
2950: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
2960: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a  n successfully..
2970: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35 7d 20 54  **.** {F12105} T
2980: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2990: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
29a0: 28 29 5d 20 69 73 20 61 6e 20 61 70 70 72 6f 70  ()] is an approp
29b0: 72 69 61 74 65 20 0a 2a 2a 20 20 20 20 20 20 20  riate .**       
29c0: 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 65 72 72 6f     non-zero erro
29d0: 72 20 63 6f 64 65 20 69 66 20 61 6e 79 20 53 51  r code if any SQ
29e0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  L statement fail
29f0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37  s..**.** {F12107
2a00: 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  } If one or more
2a10: 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
2a20: 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f  ements handed to
2a30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2a40: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2a50: 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64  turn results and
2a60: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2a70: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
2a80: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
2a90: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
2aa0: 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  nction specified
2ab0: 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
2ac0: 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
2ad0: 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63       invoked onc
2ae0: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2af0: 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20  f result..**.** 
2b00: 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68 65 20  {F12110} If the 
2b10: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
2b20: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75   a non-zero valu
2b30: 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e then [sqlite3_
2b40: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
2b50: 20 20 20 20 77 69 6c 6c 20 61 62 6f 72 74 65 64      will aborted
2b60: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2b70: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74  nt it is current
2b80: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a  ly evaluating,.*
2b90: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20  *          skip 
2ba0: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
2bb0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  QL statements, a
2bc0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
2bd0: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 20 20 20  E_ABORT]..**    
2be0: 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74        <todo>What
2bf0: 20 68 61 70 70 65 6e 73 20 74 6f 20 2a 65 72 72   happens to *err
2c00: 6d 73 67 20 68 65 72 65 3f 20 20 44 6f 65 73 20  msg here?  Does 
2c10: 74 68 65 20 72 65 73 75 6c 74 20 63 6f 64 65 20  the result code 
2c20: 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2c30: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2c40: 29 20 67 65 74 20 73 65 74 3f 3c 2f 74 6f 64 6f  ) get set?</todo
2c50: 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 33 7d  >.**.** {F12113}
2c60: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2c70: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 77 69  ec()] routine wi
2c80: 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20  ll pass its 4th 
2c90: 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67  parameter throug
2ca0: 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  h.**          as
2cb0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
2cc0: 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  er of the callba
2cd0: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  ck..**.** {F1211
2ce0: 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2cf0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2d00: 73 65 74 73 20 74 68 65 20 32 6e 64 20 70 61 72  sets the 2nd par
2d10: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
2d20: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
2d30: 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d  ck to be the num
2d40: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2d50: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2d60: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  w of.**         
2d70: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
2d80: 46 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c  F12119} The [sql
2d90: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
2da0: 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 33 72  tine sets the 3r
2db0: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
2dc0: 74 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts .**          
2dd0: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
2de0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2df0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
2e00: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
2e10: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
2e20: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
2e30: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
2e40: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
2e50: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
2e60: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2e70: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2e80: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 32 7d  ..**.** {F12122}
2e90: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2ea0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65  ec()] routine se
2eb0: 74 73 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  ts the 4th param
2ec0: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
2ed0: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
2ee0: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20   to be an array 
2ef0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
2f00: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74  trings holding t
2f10: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2f20: 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63  ames of result c
2f30: 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e  olumns as obtain
2f40: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2f50: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
2f60: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35 7d 20  .**.** {F12125} 
2f70: 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2f80: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2f90: 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c  _exec()] is NULL
2fa0: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2fb0: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28    [sqlite3_exec(
2fc0: 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 73  )] never invokes
2fd0: 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6c   a callback.  Al
2fe0: 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 20  l query.**      
2ff0: 20 20 20 20 72 65 73 75 6c 74 73 20 61 72 65 20      results are 
3000: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64  silently discard
3010: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32  ed..**.** {F1212
3020: 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  8} If an error o
3030: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
3040: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
3050: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
3060: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
3070: 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74  tements handed t
3080: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3090: 29 5d 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  )] then [sqlite3
30a0: 5f 65 78 65 63 28 29 5d 20 77 69 6c 6c 0a 2a 2a  _exec()] will.**
30b0: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30c0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
30d0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
30e0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
30f0: 46 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72  F12131} If an er
3100: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65  ror occurs while
3110: 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c   parsing or eval
3120: 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68  uating any of th
3130: 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20  e SQL.**        
3140: 20 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c    handed to [sql
3150: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 61 6e 64  ite3_exec()] and
3160: 20 69 66 20 74 68 65 20 35 74 68 20 70 61 72 61   if the 5th para
3170: 6d 65 74 65 72 20 28 65 72 72 6d 73 67 29 0a 2a  meter (errmsg).*
3180: 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73  *          to [s
3190: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
31a0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
31b0: 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
31c0: 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
31d0: 20 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67   allocated using
31e0: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
31f0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  of [sqlite3_mpri
3200: 6e 74 66 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ntf()] and.**   
3210: 20 20 20 20 20 20 20 2a 65 72 72 6d 73 67 20 69         *errmsg i
3220: 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
3230: 74 6f 20 74 68 61 74 20 6d 65 73 73 61 67 65 2e  to that message.
3240: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20  .**.** {F12134} 
3250: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3260: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 64 6f 65  c()] routine doe
3270: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
3280: 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20   value of.**    
3290: 20 20 20 20 20 20 2a 65 72 72 6d 73 67 20 69 66        *errmsg if
32a0: 20 65 72 72 6d 73 67 20 69 73 20 4e 55 4c 4c 20   errmsg is NULL 
32b0: 6f 72 20 69 66 20 74 68 65 72 65 20 61 72 65 20  or if there are 
32c0: 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a  no errors..**.**
32d0: 20 7b 46 31 32 31 33 37 7d 20 54 68 65 20 5b 73   {F12137} The [s
32e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 66  qlite3_exec()] f
32f0: 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
3300: 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
3310: 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
3320: 20 20 20 20 61 63 63 65 73 73 69 62 6c 65 20 76      accessible v
3330: 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
3340: 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
3350: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 0a  _errmsg()], and.
3360: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3370: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3380: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
3390: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31  ONS:.**.** {U121
33a0: 34 31 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  41} The first pa
33b0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
33c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74  te3_exec()] must
33d0: 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64   be an valid and
33e0: 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   open.**        
33f0: 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
3400: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ection]..**.** {
3410: 55 31 32 31 34 32 7d 20 54 68 65 20 64 61 74 61  U12142} The data
3420: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
3430: 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73  must not be clos
3440: 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20  ed while.**     
3450: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78       [sqlite3_ex
3460: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
3470: 2e 0a 2a 2a 20 0a 2a 2a 20 7b 55 31 32 31 34 33  ..** .** {U12143
3480: 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  } The calling fu
3490: 6e 63 74 69 6f 6e 20 69 73 20 73 68 6f 75 6c 64  nction is should
34a0: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
34b0: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
34c0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
34d0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
34e0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
34f0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
3500: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
3510: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
3520: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3530: 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20 54 68 65  .** {U12145} The
3540: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3550: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
3560: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3580: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
3590: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
35a0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
35b0: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
35c0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35d0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
35e0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
35f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3600: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3610: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3620: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3640: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3650: 6f 20 62 65 20 65 76 61 6c 75 74 65 64 20 2a 2f  o be evaluted */
3660: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3670: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3680: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3690: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
36a0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
36b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36d0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
36e0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
36f0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
3700: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3720: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3730: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3750: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31  Result Codes {F1
3760: 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0210}.** KEYWORD
3770: 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72  S: SQLITE_OK {er
3780: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72  ror code} {error
3790: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61   codes}.**.** Ma
37a0: 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69  ny SQLite functi
37b0: 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e  ons return an in
37c0: 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64  teger result cod
37d0: 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73  e from the set s
37e0: 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20  hown.** here in 
37f0: 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74  order to indicat
3800: 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  es success or fa
3810: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ilure..**.** See
3820: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
3830: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
3840: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3850: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
3860: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3870: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3880: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3890: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
38a0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
38b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
38c0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
38d0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
38e0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
38f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3900: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3910: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3920: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3930: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3940: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3950: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3960: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3970: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3980: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3990: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
39a0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
39b0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
39c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
39d0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
39e0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
39f0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
3a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3a10: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
3a20: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
3a30: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
3a40: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
3a50: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
3a60: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
3a70: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
3a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3a90: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
3aa0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
3ab0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
3ac0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
3ad0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3ae0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
3af0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
3b00: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
3b10: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
3b20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3b30: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
3b40: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
3b50: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
3b60: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
3b70: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
3b80: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
3b90: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
3ba0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
3bb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3bc0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
3bd0: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
3be0: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
3bf0: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
3c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
3c10: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
3c20: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
3c30: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
3c40: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
3c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
3c60: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
3c70: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
3c80: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
3c90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3ca0: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
3cb0: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
3cc0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
3cd0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
3ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3cf0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
3d00: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
3d10: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
3d20: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
3d30: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
3d40: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
3d50: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
3d60: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
3d70: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
3d80: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
3d90: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
3da0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3db0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
3dc0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
3dd0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
3de0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
3df0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
3e00: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
3e10: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
3e20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3e30: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
3e40: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
3e50: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
3e60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3e70: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
3e80: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
3e90: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
3ea0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
3eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3ec0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
3ed0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
3ee0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
3ef0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
3f00: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
3f10: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
3f20: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
3f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f40: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
3f50: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
3f60: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
3f70: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
3f80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f90: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
3fa0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
3fb0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
3fc0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3fe0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
3ff0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4000: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4010: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4020: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4030: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4040: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4050: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4060: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4070: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4080: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4090: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
40a0: 20 43 6f 64 65 73 20 7b 46 31 30 32 32 30 7d 0a   Codes {F10220}.
40b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
40c0: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
40d0: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  e} {extended err
40e0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
40f0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4100: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4110: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4120: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4130: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4140: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4150: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4160: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4170: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4180: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4190: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
41a0: 61 74 0a 2a 2a 20 6d 61 6e 79 20 6f 66 20 74 68  at.** many of th
41b0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
41c0: 20 61 72 65 20 74 6f 6f 20 63 6f 75 72 73 65 2d   are too course-
41d0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
41e0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
41f0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4200: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4210: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4220: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4230: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4240: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4250: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4260: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4270: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4280: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4290: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
42a0: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
42b0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
42c0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
42d0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
42e0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
42f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4300: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4310: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4320: 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
4330: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
4340: 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
4350: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4360: 63 6f 64 65 73 28 29 5d 0a 2a 2a 20 41 50 49 2e  codes()].** API.
4370: 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  .** .** Some of 
4380: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4390: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
43a0: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
43b0: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
43c0: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
43d0: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
43e0: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
43f0: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4400: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4410: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4420: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4430: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4440: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4450: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4460: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4470: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4480: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4490: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
44a0: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
44b0: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
44c0: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
44d0: 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41  ero..** .** INVA
44e0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
44f0: 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f  10223} The symbo
4500: 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20  lic name for an 
4510: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4520: 63 6f 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74  code always cont
4530: 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
4540: 20 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61   a related prima
4550: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61  ry result code a
4560: 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a  s a prefix..**.*
4570: 2a 20 7b 46 31 30 32 32 34 7d 20 50 72 69 6d 61  * {F10224} Prima
4580: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ry result code n
4590: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73  ames contain a s
45a0: 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63  ingle "_" charac
45b0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ter..**.** {F102
45c0: 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73  25} Extended res
45d0: 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 63  ult code names c
45e0: 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f  ontain two or mo
45f0: 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  re "_" character
4600: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 36  s..**.** {F10226
4610: 7d 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61  } The numeric va
4620: 6c 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64  lue of an extend
4630: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63  ed result code c
4640: 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
4650: 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63 20          numeric 
4660: 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f 72  value of its cor
4670: 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61  responding prima
4680: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 69  ry result code i
4690: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  t.**          it
46a0: 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  s least signific
46b0: 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23  ant 8 bits..*/.#
46c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
46d0: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
46e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
46f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4700: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4710: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28 53 51  HORT_READ    (SQ
4720: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4730: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4740: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4750: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4760: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
4770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4780: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
4790: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
47a0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
47b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
47c0: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 28 53  DIR_FSYNC     (S
47d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
47e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
47f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4800: 41 54 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  ATE      (SQLITE
4810: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4830: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4840: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4850: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
4860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4870: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 28  _UNLOCK        (
4880: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4890: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
48a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
48b0: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
48c0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
48d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
48e0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
48f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4900: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4920: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4930: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4940: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
4950: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
4960: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28 53 51  OMEM         (SQ
4970: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
4980: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
4990: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
49a0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
49b0: 74 69 6f 6e 73 20 7b 46 31 30 32 33 30 7d 0a 2a  tions {F10230}.*
49c0: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
49d0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
49e0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
49f0: 65 6e 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  en.** 3rd parame
4a00: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
4a10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
4a20: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
4a30: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
4a40: 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65  eter to the xOpe
4a50: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
4a60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
4a70: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
4a80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4a90: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
4aa0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
4ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4ac0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
4ad0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
4ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4af0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
4b00: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4b20: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
4b30: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
4b40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4b50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
4b60: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
4b70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4b80: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
4b90: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
4ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4bb0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
4bc0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
4bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4be0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
4bf0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
4c00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4c10: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
4c20: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4c40: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
4c50: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66   0x00001000.#def
4c60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4c70: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
4c80: 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66   0x00002000.#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4ca0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
4cb0: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
4cc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
4cd0: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
4ce0: 69 63 73 20 7b 46 31 30 32 34 30 7d 0a 2a 2a 0a  ics {F10240}.**.
4cf0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61  ** The xDeviceCa
4d00: 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f  pabilities metho
4d10: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
4d20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
4d30: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
4d40: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
4d50: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
4d60: 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74  the these.** bit
4d70: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
4d80: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
4d90: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
4da0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
4db0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
4dc0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
4dd0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
4de0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
4df0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
4e00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
4e10: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
4e20: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
4e30: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
4e40: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
4e50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
4e60: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
4e70: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
4e80: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
4e90: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
4ea0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
4eb0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
4ec0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
4ed0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
4ee0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
4ef0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
4f00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
4f10: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
4f20: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
4f30: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
4f40: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
4f50: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
4f60: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
4f70: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
4f80: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
4f90: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
4fa0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
4fb0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
4fc0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
4fd0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
4fe0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
4ff0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
5000: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
5010: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
5020: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
5030: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5040: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5050: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5060: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
5070: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5080: 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30  512       0x0000
5090: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
50a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
50b0: 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  1K        0x0000
50c0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
50d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
50e0: 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  2K        0x0000
50f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5100: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5110: 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  4K        0x0000
5120: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
5130: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5140: 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  8K        0x0000
5150: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
5160: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5170: 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  16K       0x0000
5180: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5190: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
51a0: 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  32K       0x0000
51b0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
51c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
51d0: 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  64K       0x0000
51e0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
51f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5200: 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30  PPEND     0x0000
5210: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5220: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5230: 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30  TIAL      0x0000
5240: 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0400../*.** CAPI
5250: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
5260: 6e 67 20 4c 65 76 65 6c 73 20 7b 46 31 30 32 35  ng Levels {F1025
5270: 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
5280: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
5290: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
52a0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
52b0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
52c0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
52d0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
52e0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
52f0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
5300: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
5310: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5320: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
5330: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
5340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5350: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
5360: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
5370: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
5380: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
5390: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
53a0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
53c0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
53d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
53e0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
53f0: 54 79 70 65 20 46 6c 61 67 73 20 7b 46 31 30 32  Type Flags {F102
5400: 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  60}.**.** When S
5410: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
5420: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
5430: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
5440: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5450: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
5460: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74  combination of t
5470: 68 65 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  he.** these inte
5480: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5490: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
54a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
54b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
54c0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
54d0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
54e0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
54f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5500: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5510: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5520: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5530: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5540: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68  t be flushed. Th
5550: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
5560: 52 4d 41 4c 20 6d 65 61 6e 73 20 0a 2a 2a 20 74  RMAL means .** t
5570: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5580: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20  nc() semantics. 
5590: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
55a0: 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20  FULL flag means 
55b0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
55c0: 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S-X style fullsy
55d0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
55e0: 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ync()..*/.#defin
55f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
5600: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
5610: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5620: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
5630: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
5640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
5650: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
5660: 30 78 30 30 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20  0x00010.../*.** 
5670: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
5680: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
5690: 20 48 61 6e 64 6c 65 20 7b 46 31 31 31 31 30 7d   Handle {F11110}
56a0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
56b0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
56c0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
56d0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 4f  en file in the O
56e0: 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 6c  S.** interface l
56f0: 61 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75 61  ayer.  Individua
5700: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 69  l OS interface i
5710: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5720: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5730: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5740: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5750: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5760: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5770: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5780: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5790: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
57a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
57b0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
57c0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
57d0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
57e0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
57f0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
5800: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
5810: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
5820: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
5830: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
5840: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
5850: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
5860: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
5870: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
5880: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
5890: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
58a0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
58b0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
58c0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
58d0: 65 63 74 20 7b 46 31 31 31 32 30 7d 0a 2a 2a 0a  ect {F11120}.**.
58e0: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
58f0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
5900: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
5910: 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69 6e 73 20  method contains 
5920: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
5930: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
5940: 68 65 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20  he this object. 
5950: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
5960: 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68  ines the.** meth
5970: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
5980: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
5990: 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74  ations against t
59a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a  he open file..**
59b0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
59c0: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
59d0: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
59e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
59f0: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
5a00: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
5a10: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
5a20: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
5a30: 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65 63  nc()..*  The sec
5a40: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 6e  ond choice is an
5a50: 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  .** OS-X style f
5a60: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53 51  ullsync.  The SQ
5a70: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20 66  LITE_SYNC_DATA f
5a80: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
5a90: 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61 74  in to.** indicat
5aa0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
5ab0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
5ac0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
5ad0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a 2a  de needs to be.*
5ae0: 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a  * synced..** .**
5af0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
5b00: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
5b10: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
5b20: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
5b30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
5b40: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
5b50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
5b60: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
5b70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
5b80: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
5b90: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
5ba0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
5bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
5bc0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
5bd0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
5be0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
5bf0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
5c00: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
5c10: 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68 65  k.  .** The xChe
5c20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
5c30: 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a   method looks.**
5c40: 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20 64   to see if any d
5c50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5c60: 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74 68  on, either in th
5c70: 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f 72  is.** process or
5c80: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
5c90: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
5ca0: 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c 0a  ng an RESERVED,.
5cb0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
5cc0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
5cd0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
5ce0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
5cf0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
5d00: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 69  ists and false i
5d10: 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  f not..** .** Th
5d20: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
5d30: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
5d40: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
5d50: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
5d60: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
5d70: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
5d80: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
5d90: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
5da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5db0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
5dc0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
5dd0: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
5de0: 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  ment.** is an in
5df0: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20  teger opcode.   
5e00: 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  The third.** arg
5e10: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
5e20: 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ic pointer which
5e30: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
5e40: 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  be a pointer.** 
5e50: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
5e60: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
5e70: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
5e80: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
5e90: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
5ea0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
5eb0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
5ec0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
5ed0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
5ee0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
5ef0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
5f00: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
5f10: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
5f20: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
5f30: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
5f40: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
5f50: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
5f60: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
5f70: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
5f80: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
5f90: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
5fa0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 6f   core reserves o
5fb0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
5fc0: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
5fd0: 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c   use. .** A [SQL
5fe0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
5ff0: 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  ATE | list of op
6000: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
6010: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
6020: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
6030: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
6040: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
6050: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
6060: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20 0a  ld use opcodes .
6070: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
6080: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
6090: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
60a0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
60b0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
60c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
60d0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
60e0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
60f0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6100: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
6110: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
6120: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
6130: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
6140: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
6150: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
6160: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
6170: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6180: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
6190: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
61a0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
61b0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
61c0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
61d0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
61e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
61f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
6200: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6210: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
6220: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
6240: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6250: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
6260: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6270: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
6280: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6290: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
62a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
62b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
62c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
62d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
62e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
62f0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6300: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6310: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6320: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
6330: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6340: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
6350: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6360: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6370: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6380: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6390: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
63a0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
63b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
63c0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
63d0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
63e0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
63f0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6400: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6410: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6420: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6430: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6440: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6450: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6460: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6470: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6480: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6490: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
64a0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
64b0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
64c0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
64d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
64e0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
64f0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6500: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6510: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6520: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6530: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6540: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6550: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6560: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6570: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6580: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
6590: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
65a0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
65b0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
65c0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
65d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
65e0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
65f0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
6600: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6610: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
6620: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6630: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
6640: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6650: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
6660: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
6670: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
6680: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
6690: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
66a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
66b0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
66c0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
66d0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
66e0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
66f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
6700: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
6710: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
6720: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6730: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
6740: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
6750: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
6760: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
6770: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
6780: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
6790: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
67a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
67b0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
67c0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
67d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
67e0: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
67f0: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
6800: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6810: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
6820: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6830: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
6840: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
6850: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
6860: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
6870: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
6880: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6890: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
68a0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
68b0: 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F11310}.**.** T
68c0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
68d0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
68e0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
68f0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
6900: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
6910: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6920: 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20  ject and to the 
6930: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
6940: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
6950: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
6960: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
6970: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
6980: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
6990: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
69a0: 20 6f 70 63 6f 64 65 20 63 61 73 65 73 20 74 68   opcode cases th
69b0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
69c0: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
69d0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
69e0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
69f0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6a00: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6a20: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6a30: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6a40: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6a50: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6a60: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6a70: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6a80: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6a90: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6aa0: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6ab0: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6ac0: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6ad0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6ae0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6af0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6b00: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b20: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6b30: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6b40: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6b50: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6b60: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6b70: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6b80: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6b90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6ba0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6bb0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6bc0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6bd0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6be0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6bf0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6c00: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6c10: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6c20: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6c30: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6c40: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6c50: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6c60: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6c70: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
6c80: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
6c90: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
6ca0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6cb0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
6cc0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
6cd0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
6ce0: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
6cf0: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
6d00: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6d10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6d20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
6d30: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
6d40: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
6d50: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
6d60: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
6d70: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
6d80: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
6d90: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
6da0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
6db0: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
6dc0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
6dd0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
6de0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
6df0: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
6e00: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
6e10: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
6e20: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
6e30: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
6e40: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
6e50: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
6e60: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
6e70: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
6e80: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
6e90: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
6ea0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
6eb0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
6ec0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
6ed0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
6ee0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
6ef0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
6f00: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
6f10: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
6f20: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
6f30: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
6f40: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
6f50: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
6f60: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
6f70: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
6f80: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
6f90: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
6fa0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
6fb0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
6fc0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
6fd0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
6fe0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
6ff0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7000: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7010: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7020: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7030: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7040: 6c 79 20 66 69 65 6c 64 73 20 69 6e 20 74 68 65  ly fields in the
7050: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a   sqlite3_vfs .**
7060: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7070: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
7080: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
7090: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
70a0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
70b0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
70c0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
70d0: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
70e0: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
70f0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
7100: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
7110: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
7120: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
7130: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
7140: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
7150: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
7160: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
7170: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
7180: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
7190: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
71a0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
71b0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
71c0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  les..**.** {F111
71d0: 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  41} SQLite will 
71e0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
71f0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72  he zFilename str
7200: 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ing passed to.**
7210: 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75   xOpen() is a fu
7220: 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67  ll pathname as g
7230: 65 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c  enerated by xFul
7240: 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a  lPathname() and.
7250: 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69  ** that the stri
7260: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
7270: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
7280: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
7290: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e  .** called.  {EN
72a0: 44 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74  D} So the [sqlit
72b0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f  e3_file] can sto
72c0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
72d0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
72e0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
72f0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
7300: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
7310: 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ason..**.** {F11
7320: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61  142} The flags a
7330: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
7340: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
7350: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
7360: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7370: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
7380: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
7390: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
73a0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
73b0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
73c0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
73d0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
73e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
73f0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
7400: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7410: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20  E]. {END}.** If 
7420: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
7430: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
7440: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
7450: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
7460: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
7470: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
7480: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
7490: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a  tFlags may be.**
74a0: 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31   set..** .** {F1
74b0: 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c  1143} SQLite wil
74c0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
74d0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
74e0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
74f0: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
7500: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
7510: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
7520: 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ed:.** .** <ul>.
7530: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7540: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
7550: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7560: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
7570: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7580: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
7590: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
75a0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
75b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
75c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
75d0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
75e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
75f0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
7600: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7610: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
7620: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  ].** </ul> {END}
7630: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
7640: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
7650: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
7660: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
7670: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74   to.** changes t
7680: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
7690: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
76a0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
76b0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
76c0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
76d0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
76e0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 2c  ery or rollback,
76f0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
7700: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
7710: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
7720: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
7730: 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72 65 0a 2a  is journal are.*
7740: 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f 70 2e 20  * also a no-op. 
7750: 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
7760: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
7770: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 49   return SQLITE_I
7780: 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20 74 68 65 20  OERR..** Or the 
7790: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
77a0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
77b0: 68 65 20 61 20 64 61 74 61 62 61 73 65 20 66 69  he a database fi
77c0: 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 64 6f  le will.** be do
77d0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
77e0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
77f0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
7800: 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a 2a 20 61 6e  ndom order.** an
7810: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7820: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7830: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7840: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7850: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7860: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7870: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7880: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
7890: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
78a0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
78b0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
78c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
78d0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
78e0: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
78f0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7900: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7910: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7920: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7930: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7940: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7950: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7960: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7970: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7980: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
7990: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
79a0: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
79b0: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
79c0: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
79d0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
79e0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
79f0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7a00: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7a10: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7a20: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7a30: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7a40: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7a50: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7a60: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7a70: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7a80: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7a90: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 69 73  tes of memory is
7aa0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
7ab0: 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c 64  Lite .** to hold
7ac0: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
7ad0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
7ae0: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
7af0: 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rd .** argument 
7b00: 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44 7d  to xOpen.  {END}
7b10: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
7b20: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
7b30: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
7b40: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
7b50: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
7b60: 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a 2a  ll it in..** .**
7b70: 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66 6c   {F11149} The fl
7b80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7b90: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
7ba0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
7bb0: 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 74  EXISTS] .** to t
7bc0: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
7bd0: 74 61 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tance of a file,
7be0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  .** or [SQLITE_A
7bf0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
7c00: 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a   to test to see.
7c10: 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73 20  ** if a file is 
7c20: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
7c30: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
7c40: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
7c50: 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  * to test to see
7c60: 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61 74   if a file is at
7c70: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
7c80: 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c 65    {END} The file
7c90: 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64 69   can be a .** di
7ca0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a 20  rectory..** .** 
7cb0: 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20  {F11150} SQLite 
7cc0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
7cd0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
7ce0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20  Pathname+1 byte 
7cf0: 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75  for.** the outpu
7d00: 74 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47  t buffers for xG
7d10: 65 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20 78  etTempname and x
7d20: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 46  FullPathname. {F
7d30: 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63 74  11151} The exact
7d40: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20  .** size of the 
7d50: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 69 73  output buffer is
7d60: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
7d70: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
7d80: 6f 74 68 20 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e  oth .** methods.
7d90: 20 7b 45 4e 44 7d 20 49 66 20 74 68 65 20 6f 75   {END} If the ou
7da0: 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20 6e  tput buffer is n
7db0: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
7dc0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
7dd0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
7de0: 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20  turned. As this 
7df0: 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  is handled as a 
7e00: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
7e10: 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d  QLite,.** vfs im
7e20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7e30: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f  ould endeavor to
7e40: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
7e50: 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50   setting .** mxP
7e60: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
7e70: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
7e80: 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  value..** .** Th
7e90: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
7ea0: 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78   xSleep(), and x
7eb0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e  CurrentTime() in
7ec0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
7ed0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
7ee0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
7ef0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
7f00: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
7f10: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
7f20: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
7f30: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
7f40: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
7f50: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
7f60: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
7f70: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
7f80: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
7f90: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
7fa0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
7fb0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
7fc0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
7fd0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
7fe0: 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a  btained.  The.**
7ff0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
8000: 20 63 61 75 73 65 20 74 68 65 20 63 61 6c 6c 69   cause the calli
8010: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
8020: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
8030: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
8040: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
8050: 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65  ven.  The xCurre
8060: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
8070: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
8080: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
8090: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
80a0: 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e  ate and.** time.
80b0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
80c0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
80d0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75  qlite3_vfs;.stru
80e0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
80f0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
8100: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
8110: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
8120: 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74   number */.  int
8130: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
8140: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
8150: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
8160: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
8170: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
8180: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
8190: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
81a0: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
81b0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
81c0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
81d0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
81e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
81f0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
8200: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
8210: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
8220: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
8230: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
8240: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
8250: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
8260: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
8270: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
8280: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8290: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
82a0: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
82b0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
82c0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
82d0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
82e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
82f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8300: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
8310: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
8320: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8330: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8340: 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  e, int flags);. 
8350: 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 6e   int (*xGetTempn
8360: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
8370: 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  *, int nOut, cha
8380: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
8390: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
83a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
83b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
83c0: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
83d0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
83e0: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
83f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8400: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
8410: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
8420: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
8430: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
8440: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
8450: 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28  void *(*xDlSym)(
8460: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
8470: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
8480: 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64  zSymbol);.  void
8490: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
84a0: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
84b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
84c0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
84d0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
84e0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
84f0: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
8500: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
8510: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
8520: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
8530: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
8540: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f  *, double*);.  /
8550: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
8560: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
8570: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
8580: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
8590: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
85a0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
85b0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
85c0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
85d0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
85e0: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
85f0: 20 6d 65 74 68 6f 64 20 7b 46 31 31 31 39 30 7d   method {F11190}
8600: 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39 31 7d 20  .**.** {F11191} 
8610: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
8620: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
8630: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
8640: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
8650: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8660: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
8670: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
8680: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65  {END}  They dete
8690: 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 6b 69 6e  rmine.** the kin
86a0: 64 20 6f 66 20 77 68 61 74 20 6b 69 6e 64 20 6f  d of what kind o
86b0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
86c0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
86d0: 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66   is.** looking f
86e0: 6f 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69  or.  {F11192} Wi
86f0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
8700: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
8710: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
8720: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20  imply checks to 
8730: 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20  see if the file 
8740: 65 78 69 73 74 73 2e 20 7b 46 31 31 31 39 33 7d  exists. {F11193}
8750: 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   With.** SQLITE_
8760: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8770: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
8780: 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20 73  thod checks to s
8790: 65 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c  ee.** if the fil
87a0: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
87b0: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
87c0: 20 20 7b 46 31 31 31 39 34 7d 20 57 69 74 68 0a    {F11194} With.
87d0: 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ** SQLITE_ACCESS
87e0: 5f 52 45 41 44 20 74 68 65 20 78 41 63 63 65 73  _READ the xAcces
87f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8800: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
8810: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8820: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
8830: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
8840: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
8850: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8860: 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e  ADWRITE 1.#defin
8870: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8880: 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a  READ      2../*.
8890: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
88a0: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
88b0: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
88c0: 6f 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a  odes {F12200}.**
88d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
88e0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
88f0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
8900: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
8910: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  les the.** [SQLI
8920: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
8930: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
8940: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
8950: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54 68 65  f SQLite..** The
8960: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8970: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
8980: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
8990: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
89a0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
89b0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
89c0: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d  :.**.** {F12201}
89d0: 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62   Each new [datab
89e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
89f0: 68 61 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  has the .**     
8a00: 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72       [extended r
8a10: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
8a20: 74 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ture.**         
8a30: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
8a40: 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ault..**.** {F12
8a50: 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  202} The [sqlite
8a60: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
8a70: 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e  t_codes(D,F)] in
8a80: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 65 6e 61  terface will ena
8a90: 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
8aa0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
8ab0: 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20   codes] for the 
8ac0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
8ad0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8ae0: 6e 5d 20 44 20 69 66 20 74 68 65 20 46 20 70 61  n] D if the F pa
8af0: 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
8b00: 20 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72 20      is true, or 
8b10: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
8b20: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
8b30: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
8b40: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
8b50: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
8b60: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
8b70: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
8b80: 65 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32  ert Rowid {F1222
8b90: 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e  0}.**.** Each en
8ba0: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
8bb0: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
8bc0: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
8bd0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
8be0: 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77   called the "row
8bf0: 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69  id". The rowid i
8c00: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
8c10: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
8c20: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
8c30: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
8c40: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
8c50: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
8c60: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
8c70: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
8c80: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
8c90: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65  lumns. If.** the
8ca0: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
8cb0: 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45  umn of type INTE
8cc0: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
8cd0: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
8ce0: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
8cf0: 6e 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  n alias for the 
8d00: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
8d10: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
8d20: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
8d30: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
8d40: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
8d50: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ERT into the dat
8d60: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64  abase from the d
8d70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8d80: 6f 6e 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74  on.** shown in t
8d90: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
8da0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
8db0: 73 66 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20  sful inserts.** 
8dc0: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
8dd0: 65 64 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62  ed on this datab
8de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
8df0: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
8e00: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
8e10: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
8e20: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
8e30: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
8e40: 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20  the.** inserted 
8e50: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
8e60: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
8e70: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
8e80: 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e  rigger.** is run
8e90: 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20  ning.  But once 
8ea0: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
8eb0: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
8ec0: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
8ed0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
8ee0: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
8ef0: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
8f00: 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74   before the.** t
8f10: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
8f20: 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68  .** An INSERT th
8f30: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
8f40: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
8f50: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
8f60: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e  ** successful in
8f70: 73 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f  sert and does no
8f80: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
8f90: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
8fa0: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
8fb0: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20   Thus INSERT OR 
8fc0: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
8fd0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
8fe0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
8ff0: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
9000: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
9010: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
9020: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
9030: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
9040: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
9050: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45  ails.  When INSE
9060: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a  RT OR REPLACE .*
9070: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
9080: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
9090: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
90a0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
90b0: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
90c0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
90d0: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
90e0: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
90f0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
9100: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
9110: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
9120: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
9130: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
9140: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
9150: 72 66 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f  rface. .**.** Fo
9160: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
9170: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
9180: 61 6e 20 69 6e 73 65 72 74 20 69 73 20 63 6f 6e  an insert is con
9190: 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
91a0: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
91b0: 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
91c0: 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
91d0: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ck..**.** INVARI
91e0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
91f0: 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  221} The [sqlite
9200: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
9210: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
9220: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
9230: 20 20 20 20 20 20 20 20 72 6f 77 69 64 20 6f 66          rowid of
9240: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
9250: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65   successful inse
9260: 72 74 20 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 20  rt done.**      
9270: 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20      on the same 
9280: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9290: 69 6f 6e 20 61 6e 64 20 77 69 74 68 69 6e 20 74  ion and within t
92a0: 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
92b0: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
92c0: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
92d0: 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20  there have.**   
92e0: 20 20 20 20 20 20 20 62 65 65 6e 20 6e 6f 20 71         been no q
92f0: 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74  ualifying insert
9300: 73 20 6f 6e 20 74 68 61 74 20 63 6f 6e 6e 65 63  s on that connec
9310: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  tion..**.** {F12
9320: 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  223} The [sqlite
9330: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
9340: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
9350: 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
9360: 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77      same value w
9370: 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
9380: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
9390: 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20   context.**     
93a0: 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79       immediately
93b0: 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65   before and afte
93c0: 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a  r a ROLLBACK..**
93d0: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
93e0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20  .**.** {U12232} 
93f0: 49 66 20 73 65 70 61 72 61 74 65 20 74 68 72 65  If separate thre
9400: 61 64 20 64 6f 65 73 20 61 20 6e 65 77 20 69 6e  ad does a new in
9410: 73 65 72 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  sert on the same
9420: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
9430: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9440: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
9450: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
9460: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20  rowid()].**     
9470: 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73       function is
9480: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
9490: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
94a0: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c  st insert rowid,
94b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
94c0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
94d0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
94e0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
94f0: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  id()] is.**     
9500: 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62       unpredictab
9510: 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
9520: 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
9530: 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
9540: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73  .**          las
9550: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a  t insert rowid..
9560: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
9570: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
9580: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
9590: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
95a0: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
95b0: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
95c0: 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 34 30  Modified {F12240
95d0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  }.**.** This fun
95e0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
95f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
9600: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
9610: 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
9620: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
9630: 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
9640: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
9650: 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
9660: 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e  nt.** on the con
9670: 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
9680: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
9690: 61 72 61 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a  arameter.  Only.
96a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ** changes that 
96b0: 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
96c0: 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e  cified by the IN
96d0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
96e0: 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65  .** DELETE state
96f0: 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
9700: 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
9710: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
9720: 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e  * triggers are n
9730: 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20  ot counted. Use 
9740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
9750: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
9760: 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e  nction.** to fin
9770: 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
9780: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
9790: 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
97a0: 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
97b0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77  rs..**.** A "row
97c0: 20 63 68 61 6e 67 65 73 22 20 69 73 20 61 20 63   changes" is a c
97d0: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
97e0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
97f0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
9800: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
9810: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
9820: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
9830: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
9840: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
9850: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
9860: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
9870: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
9880: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
9890: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
98a0: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
98b0: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
98c0: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
98d0: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
98e0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
98f0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
9900: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
9910: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
9920: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
9930: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
9940: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
9950: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
9960: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
9970: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
9980: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
9990: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
99a0: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
99b0: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
99c0: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
99d0: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
99e0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
99f0: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
9a00: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
9a10: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
9a20: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
9a30: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
9a40: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
9a50: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
9a60: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
9a70: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
9a80: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
9a90: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
9aa0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
9ab0: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
9ac0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
9ad0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
9ae0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
9af0: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
9b00: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
9b10: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
9b20: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
9b30: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
9b40: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
9b50: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
9b60: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77  text..**.** So w
9b70: 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
9b80: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
9b90: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
9ba0: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
9bb0: 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
9bc0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
9bd0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
9be0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
9bf0: 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
9c00: 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
9c10: 6c 2e 0a 2a 2a 20 57 69 74 68 69 6e 20 74 68 65  l..** Within the
9c20: 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
9c30: 65 72 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  er, the sqlite3_
9c40: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
9c50: 61 63 65 0a 2a 2a 20 63 61 6e 20 62 65 20 63 61  ace.** can be ca
9c60: 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
9c70: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
9c80: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
9c90: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
9ca0: 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
9cb0: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
9cc0: 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
9cd0: 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
9ce0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
9cf0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
9d00: 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
9d10: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
9d20: 65 20 69 6e 20 63 68 61 6e 67 65 73 0a 2a 2a 20  e in changes.** 
9d30: 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
9d40: 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 65 79  ggers since they
9d50: 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
9d60: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53  context..**.** S
9d70: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
9d80: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
9d90: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
9da0: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48   without.** a WH
9db0: 45 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72  ERE clause by dr
9dc0: 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
9dd0: 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
9de0: 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a    (This is much.
9df0: 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ** faster than g
9e00: 6f 69 6e 67 20 74 68 72 6f 75 67 68 20 61 6e 64  oing through and
9e10: 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
9e20: 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
9e30: 6f 6d 20 74 68 65 0a 2a 2a 20 74 61 62 6c 65 2e  om the.** table.
9e40: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
9e50: 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  is optimization,
9e60: 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69   the deletions i
9e70: 6e 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  n.** "DELETE FRO
9e80: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
9e90: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
9ea0: 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75   will not be cou
9eb0: 6e 74 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 73  nted.** by the s
9ec0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
9ed0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
9ee0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
9ef0: 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67  nctions..** To g
9f00: 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63  et an accurate c
9f10: 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
9f20: 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74  er of rows delet
9f30: 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45  ed, use.** "DELE
9f40: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48  TE FROM table WH
9f50: 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a  ERE 1" instead..
9f60: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
9f70: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 34 31 7d  :.**.** {F12241}
9f80: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   The [sqlite3_ch
9f90: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
9fa0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
9fb0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
9fc0: 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20      row changes 
9fd0: 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f  caused by the mo
9fe0: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
9ff0: 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20  , UPDATE,.**    
a000: 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20        or DELETE 
a010: 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
a020: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
a030: 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a  onnection and.**
a040: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e            within
a050: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
a060: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
a070: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
a080: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
a090: 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
a0a0: 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
a0b0: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
a0c0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
a0d0: 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
a0e0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
a0f0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
a100: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
a110: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
a120: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
a130: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
a140: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
a150: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
a160: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
a170: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
a180: 20 75 6e 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a   unmeaningful..*
a190: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
a1a0: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
a1b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a1c0: 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
a1d0: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20  f Rows Modified 
a1e0: 7b 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20  {F12260}.***.** 
a1f0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
a200: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
a210: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
a220: 63 61 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53  caused.** by INS
a230: 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
a240: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
a250: 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
a260: 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61  ase handle.** wa
a270: 73 20 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 63  s opened.  The c
a280: 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c  ount includes al
a290: 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61  l changes from a
a2a0: 6c 6c 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f  ll trigger.** co
a2b0: 6e 74 65 78 74 73 2e 20 20 42 75 74 20 74 68 65  ntexts.  But the
a2c0: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
a2d0: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
a2e0: 75 73 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65  used to.** imple
a2f0: 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e  ment REPLACE con
a300: 73 74 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c  straints, do rol
a310: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
a320: 70 72 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f  processing,.** o
a330: 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f  r DROP table pro
a340: 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20  cessing..** The 
a350: 63 68 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63  changes.** are c
a360: 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  ounted as soon a
a370: 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
a380: 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
a390: 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a  is completed .**
a3a0: 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
a3b0: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70  ment handle is p
a3c0: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
a3d0: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a  3_reset()] or .*
a3e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
a3f0: 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
a400: 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
a410: 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
a420: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
a430: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48   without.** a WH
a440: 45 52 45 20 63 6c 61 75 73 65 20 62 79 20 64 72  ERE clause by dr
a450: 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
a460: 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
a470: 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a    (This is much.
a480: 2a 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ** faster than g
a490: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
a4a0: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
a4b0: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
a4c0: 20 66 6f 72 6d 20 74 68 65 20 74 61 62 6c 65 2e   form the table.
a4d0: 29 20 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a  )  Because of.**
a4e0: 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69   this optimizati
a4f0: 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63  on, the change c
a500: 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45  ount for "DELETE
a510: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c   FROM table" wil
a520: 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67  l be.** zero reg
a530: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
a540: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
a550: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
a560: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a  inally in the.**
a570: 20 74 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61   table. To get a
a580: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
a590: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
a5a0: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
a5b0: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
a5c0: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
a5d0: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
a5e0: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
a5f0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
a600: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
a610: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
a620: 2a 2a 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20  ** .** {F12261} 
a630: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
a640: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65  al_changes()] re
a650: 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
a660: 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
a670: 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65     of row change
a680: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
a690: 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f  RT, UPDATE, and/
a6a0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20  or DELETE.**    
a6b0: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
a6c0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
a6d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a6e0: 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20  n], in any.**   
a6f0: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
a700: 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68  ontext, since th
a710: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
a720: 63 74 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20  ction was.**    
a730: 20 20 20 20 20 20 63 72 65 61 74 65 64 2e 0a 2a        created..*
a740: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
a750: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d  :.**.** {U12264}
a760: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
a770: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
a780: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
a790: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a7a0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
a7b0: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
a7c0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
a7d0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
a7e0: 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20  the value .**   
a7f0: 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
a800: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
a810: 20 61 6e 64 20 75 6e 6d 65 61 6e 69 6e 67 66 75   and unmeaningfu
a820: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
a830: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
a840: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
a850: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
a860: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
a870: 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32 32  ning Query {F122
a880: 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  70}.**.** This f
a890: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
a8a0: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
a8b0: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
a8c0: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
a8d0: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
a8e0: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
a8f0: 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
a900: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
a910: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
a920: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
a930: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
a940: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
a950: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
a960: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
a970: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
a980: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
a990: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
a9a0: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
a9b0: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
a9c0: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
a9d0: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
a9e0: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
a9f0: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
aa00: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
aa10: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
aa20: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
aa30: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
aa40: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
aa50: 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  h a database con
aa60: 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a 20  nection that.** 
aa70: 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
aa80: 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
aa90: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
aaa0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
aab0: 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 69 73 20  ** If an SQL is 
aac0: 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
aad0: 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
aae0: 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   when sqlite3_in
aaf0: 74 65 72 72 75 70 74 28 29 0a 2a 2a 20 69 73 20  terrupt().** is 
ab00: 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
ab10: 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
ab20: 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74 6f  n opportunity to
ab30: 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 2e   be interrupted.
ab40: 0a 2a 2a 20 49 74 20 6d 69 67 68 74 20 63 6f 6e  .** It might con
ab50: 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
ab60: 69 6f 6e 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f  ion..** An SQL o
ab70: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
ab80: 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
ab90: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
aba0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 20  ITE_INTERRUPT]. 
abb0: 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70   If the interrup
abc0: 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
abd0: 6e 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45 52  n is an.** INSER
abe0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
abf0: 4c 45 54 45 20 74 68 61 74 20 69 73 20 69 6e 73  LETE that is ins
ac00: 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
ac10: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a  transaction, .**
ac20: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
ac30: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69 6c   transaction wil
ac40: 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
ac50: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
ac60: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ac70: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ac80: 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
ac90: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
aca0: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
acb0: 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  rted after sqlit
acc0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
acd0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  eturns..**.** IN
ace0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
acf0: 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71  {F12271} The [sq
ad00: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ad10: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
ad20: 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e  l force all runn
ad30: 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
ad40: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
ad50: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
ad60: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
ad70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
ad80: 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20          to halt 
ad90: 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67  after processing
ada0: 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64   at most one add
adb0: 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a  itional row of.*
adc0: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 2e  *          data.
add0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20  .**.** {F12272} 
ade0: 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
adf0: 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  t that is interr
ae00: 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  upted by [sqlite
ae10: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
ae20: 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
ae30: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
ae40: 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a  NTERRUPT]..**.**
ae50: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
ae60: 0a 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66 20  .** {U12279} If 
ae70: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
ae80: 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
ae90: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
aea0: 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20  terrupt()].**   
aeb0: 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e         is runnin
aec0: 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
aed0: 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
aee0: 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
aef0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
af00: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
af10: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
af20: 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
af30: 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
af40: 70 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a  plete {F10510}.*
af50: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
af60: 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 66  nes are useful f
af70: 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  or command-line 
af80: 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
af90: 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
afa0: 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
afb0: 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
afc0: 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c  m complete a SQL
afd0: 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
afe0: 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
aff0: 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
b000: 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
b010: 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
b020: 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
b030: 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  g.  These routin
b040: 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  es return true i
b050: 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
b060: 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
b070: 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
b080: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 41  QL statement.  A
b090: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
b0a0: 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
b0b0: 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
b0c0: 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
b0d0: 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
b0e0: 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20 6f  not a fragment o
b0f0: 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54 52  f a.** CREATE TR
b100: 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
b110: 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61    Semicolons tha
b120: 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
b130: 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
b140: 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
b150: 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
b160: 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
b170: 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
b180: 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
b190: 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
b1a0: 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
b1b0: 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
b1c0: 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
b1d0: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
b1e0: 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
b1f0: 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
b200: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
b210: 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
b220: 53 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20 77 69  SQL and.** so wi
b230: 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
b240: 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
b250: 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
b260: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
b270: 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20  ** {F10511} The 
b280: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
b290: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
b2a0: 6f 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63  omplete16() func
b2b0: 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tions.**        
b2c0: 20 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e    return true (n
b2d0: 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20  on-zero) if and 
b2e0: 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74  only if the last
b2f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
b300: 2d 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b 65  -whitespace toke
b310: 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74  n in their input
b320: 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20   is a semicolon 
b330: 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
b340: 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65   is not in betwe
b350: 65 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64  en the BEGIN and
b360: 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45   END of a CREATE
b370: 20 54 52 49 47 47 45 52 0a 2a 2a 20 20 20 20 20   TRIGGER.**     
b380: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a       statement..
b390: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
b3a0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32  S:.**.** {U10512
b3b0: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73  } The input to s
b3c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
b3d0: 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ) must be a zero
b3e0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
b3f0: 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
b400: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30  ring..**.** {U10
b410: 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74  513} The input t
b420: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  o sqlite3_comple
b430: 74 65 31 36 28 29 20 6d 75 73 74 20 62 65 20 61  te16() must be a
b440: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b450: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
b460: 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
b470: 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
b480: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
b490: 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
b4a0: 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
b4b0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
b4c0: 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
b4d0: 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
b4e0: 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
b4f0: 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
b500: 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
b510: 72 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a  rrors {F12310}.*
b520: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
b530: 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63  e identifies a c
b540: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
b550: 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a 2a   that might be.*
b560: 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  * invoked whenev
b570: 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  er an attempt is
b580: 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
b590: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a  database table .
b5a0: 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  ** that another 
b5b0: 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73  thread or proces
b5c0: 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
b5d0: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
b5e0: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
b5f0: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
b600: 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
b610: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
b620: 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
b630: 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
b640: 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
b650: 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  lock..** If the 
b660: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
b670: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
b680: 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  the.** callback 
b690: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
b6a0: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
b6b0: 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72 73  ts.  The.** firs
b6c0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
b6d0: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
b6e0: 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
b6f0: 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
b700: 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
b710: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
b720: 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73 65  routine.  The se
b730: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
b740: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
b750: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
b760: 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
b770: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
b780: 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
b790: 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
b7a0: 67 20 65 76 65 6e 74 2e 20 20 20 49 66 20 74 68  g event.   If th
b7b0: 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
b7c0: 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
b7d0: 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
b7e0: 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
b7f0: 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
b800: 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
b810: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
b820: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
b830: 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
b840: 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  rned..** If the 
b850: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
b860: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
b870: 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
b880: 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
b890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
b8a0: 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
b8b0: 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
b8c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
b8d0: 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
b8e0: 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
b8f0: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 0a   guarantee that.
b900: 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  ** it will be in
b910: 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72 65  voked when there
b920: 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
b930: 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69 74  ion..** If SQLit
b940: 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
b950: 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
b960: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  usy handler coul
b970: 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20 61  d result in.** a
b980: 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
b990: 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
b9a0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
b9b0: 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  USY] or.** [SQLI
b9c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
b9d0: 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
b9e0: 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a 20 62 75 73  oking the.** bus
b9f0: 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
ba00: 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
ba10: 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
ba20: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
ba30: 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
ba40: 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
ba50: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
ba60: 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
ba70: 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
ba80: 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
ba90: 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
baa0: 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
bab0: 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
bac0: 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
bad0: 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
bae0: 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
baf0: 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
bb00: 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
bb10: 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
bb20: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
bb30: 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
bb40: 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
bb50: 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
bb60: 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
bb70: 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
bb80: 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
bb90: 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
bba0: 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
bbb0: 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
bbc0: 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
bbd0: 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
bbe0: 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
bbf0: 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
bc00: 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
bc10: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
bc20: 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
bc30: 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
bc40: 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
bc50: 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
bc60: 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
bc70: 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
bc80: 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
bc90: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
bca0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
bcb0: 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
bcc0: 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
bcd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
bce0: 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
bcf0: 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
bd00: 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
bd10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
bd20: 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
bd30: 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
bd40: 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
bd50: 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
bd60: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
bd70: 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
bd80: 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
bd90: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
bda0: 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
bdb0: 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
bdc0: 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
bdd0: 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
bde0: 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
bdf0: 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
be00: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
be10: 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
be20: 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
be30: 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
be40: 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
be50: 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
be60: 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
be70: 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
be80: 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
be90: 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
bea0: 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
beb0: 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
bec0: 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
bed0: 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
bee0: 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
bef0: 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
bf00: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
bf10: 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
bf20: 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
bf30: 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
bf40: 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
bf50: 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
bf60: 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
bf70: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
bf80: 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73  w.sqlite.org/cvs
bf90: 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
bfa0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
bfb0: 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
bfc0: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
bfd0: 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
bfe0: 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
bff0: 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
c000: 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
c010: 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68  rtant..**..** Th
c020: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
c030: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
c040: 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
c050: 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  r each database.
c060: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
c070: 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
c080: 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
c090: 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20 6f  s any previous o
c0a0: 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ne. .** Note tha
c0b0: 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
c0c0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
c0d0: 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  )] will also set
c0e0: 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68 65   or clear.** the
c0f0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
c100: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
c110: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20  .**.** {F12311} 
c120: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  The [sqlite3_bus
c130: 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e  y_handler()] fun
c140: 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
c150: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  he busy handler.
c160: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
c170: 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74 61  back in the data
c180: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c190: 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
c1a0: 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  e 1st.**        
c1b0: 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
c1c0: 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
c1d0: 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64 20 62  ler identified b
c1e0: 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33 72  y the 2nd and 3r
c1f0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  d.**          pa
c200: 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
c210: 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64 65 66  {F12312} The def
c220: 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c 65  ault busy handle
c230: 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62 61  r for new databa
c240: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69  se connections i
c250: 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s NULL..**.** {F
c260: 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20  12314} When two 
c270: 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73 65  or more database
c280: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72   connection shar
c290: 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65  e a common cache
c2a0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
c2b0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
c2c0: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
c2d0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65  connection curre
c2e0: 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ntly using.**   
c2f0: 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65         the cache
c300: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
c310: 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75   the cache encou
c320: 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a  nters a lock..**
c330: 0a 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 20  .** {F12316} If 
c340: 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  a busy handler c
c350: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
c360: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53  zero, then the S
c370: 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  QLite.**        
c380: 20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74    interface that
c390: 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f   provoked the lo
c3a0: 63 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c  cking event will
c3b0: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
c3c0: 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 55 53 59      [SQLITE_BUSY
c3d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38  ]..**.** {F12318
c3e0: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
c3f0: 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20 68  vokes the busy h
c400: 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f 20  andler with two 
c410: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
c420: 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 61  *          are a
c430: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69   copy of the poi
c440: 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20 62 79  nter supplied by
c450: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
c460: 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
c470: 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
c480: 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61  handler()] and a
c490: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
c4a0: 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a  mber of prior.**
c4b0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61            invoca
c4c0: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73  tions of the bus
c4d0: 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
c4e0: 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
c4f0: 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  vent..**.** LIMI
c500: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
c510: 55 31 32 33 31 39 7d 20 41 20 62 75 73 79 20 68  U12319} A busy h
c520: 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f  andler should no
c530: 74 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65  t call close the
c540: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
c550: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
c560: 20 6f 72 20 70 72 65 70 61 72 65 64 20 73 74 61   or prepared sta
c570: 74 65 6d 65 6e 74 20 74 68 61 74 20 69 6e 76 6f  tement that invo
c580: 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
c590: 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
c5a0: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
c5b0: 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
c5c0: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
c5d0: 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
c5e0: 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
c5f0: 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31 32 33  sy Timeout {F123
c600: 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  40}.**.** This r
c610: 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
c620: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
c630: 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
c640: 65 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65  er].** that slee
c650: 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65 20 77  ps for a while w
c660: 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69  hen a.** table i
c670: 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
c680: 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65  andler will slee
c690: 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
c6a0: 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65   until .** at le
c6b0: 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
c6c0: 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
c6d0: 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f 6e 65  g have been done
c6e0: 2e 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72  . {F12343} After
c6f0: 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  .** "ms" millise
c700: 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
c710: 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  g, the handler r
c720: 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 0a 2a  eturns 0 which.*
c730: 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  * causes [sqlite
c740: 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
c750: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
c760: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
c770: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
c780: 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  ** Calling this 
c790: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
c7a0: 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
c7b0: 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
c7c0: 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
c7d0: 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
c7e0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  rs..**.** There 
c7f0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
c800: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
c810: 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
c820: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
c830: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66 20 61  onnection.  If a
c840: 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
c850: 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65 64 20  ler was defined 
c860: 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c   .** (using [sql
c870: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
c880: 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
c890: 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
c8a0: 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
c8b0: 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
c8c0: 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
c8d0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
c8e0: 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 65  .** {F12341} The
c8f0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
c900: 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69  imeout()] functi
c910: 6f 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  on overrides any
c920: 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
c930: 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
c940: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b  _timeout()] or [
c950: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
c960: 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a  dler()] setting.
c970: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
c980: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
c990: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
c9a0: 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20 74  ** {F12343} If t
c9b0: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
c9c0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
c9d0: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
c9e0: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
c9f0: 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74        or equal t
ca00: 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  o zero, then the
ca10: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
ca20: 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74   cleared so that
ca30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
ca40: 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b   subsequent lock
ca50: 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64  ing events immed
ca60: 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53  iately return [S
ca70: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
ca80: 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20 74  ** {F12344} If t
ca90: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
caa0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
cab0: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
cac0: 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20  a positive.**   
cad0: 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c         number N,
cae0: 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e   then a busy han
caf0: 64 6c 65 72 20 69 73 20 73 65 74 20 74 68 61 74  dler is set that
cb00: 20 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c   repeatedly call
cb10: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
cb20: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
cb30: 64 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e 74  d in the VFS int
cb40: 65 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69 74  erface until eit
cb50: 68 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  her the.**      
cb60: 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20      lock clears 
cb70: 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d  or until the cum
cb80: 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74 69  ulative sleep ti
cb90: 6d 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  me reported back
cba0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
cbb0: 78 53 6c 65 65 70 28 29 20 65 78 63 65 65 64 73  xSleep() exceeds
cbc0: 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e   N milliseconds.
cbd0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
cbe0: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
cbf0: 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
cc00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cc10: 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
cc20: 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
cc30: 67 20 51 75 65 72 69 65 73 20 7b 46 31 32 33 37  g Queries {F1237
cc40: 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0}.**.** Definit
cc50: 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
cc60: 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
cc70: 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
cc80: 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
cc90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
cca0: 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
ccb0: 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
ccc0: 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
ccd0: 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
cce0: 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
ccf0: 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
cd00: 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
cd10: 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
cd20: 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
cd30: 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
cd40: 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
cd50: 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
cd60: 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
cd70: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
cd80: 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
cd90: 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
cda0: 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
cdb0: 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
cdc0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
cdd0: 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
cde0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
cdf0: 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
ce00: 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
ce10: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
ce20: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
ce30: 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ** UTF-8 strings
ce40: 2e 20 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  .  There are (N+
ce50: 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
ce60: 20 74 68 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a   the array.  .**
ce70: 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
ce80: 6e 74 65 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a  nters point to z
ce90: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
cea0: 74 72 69 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20  trings that .** 
ceb0: 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
cec0: 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
ced0: 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
cee0: 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
cef0: 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
cf00: 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20  sults.  NULL.** 
cf10: 76 61 6c 75 65 73 20 61 72 65 20 67 69 76 65 20  values are give 
cf20: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
cf30: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
cf40: 73 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69  s are in.** thei
cf50: 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
cf60: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 72  minated string r
cf70: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
cf80: 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
cf90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
cfa0: 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
cfb0: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
cfc0: 67 68 74 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  ght consists of 
cfd0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
cfe0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
cff0: 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
d000: 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
d010: 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
d020: 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
d030: 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
d040: 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
d050: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
d060: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
d070: 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
d080: 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
d090: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
d0a0: 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
d0b0: 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
d0c0: 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
d0d0: 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
d0e0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
d0f0: 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
d100: 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
d110: 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
d120: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
d130: 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
d140: 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
d150: 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
d160: 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
d170: 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
d180: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
d190: 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
d1a0: 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
d1b0: 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
d1c0: 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
d1d0: 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
d1e0: 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
d1f0: 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
d200: 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
d210: 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
d220: 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
d230: 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
d240: 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
d250: 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
d260: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
d270: 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
d280: 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
d290: 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
d2a0: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
d2b0: 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
d2c0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d2d0: 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
d2e0: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d2f0: 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
d300: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
d310: 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
d320: 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
d330: 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
d340: 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
d350: 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
d360: 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
d370: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d380: 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
d390: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
d3a0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
d3b0: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
d3c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
d3d0: 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
d3e0: 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
d3f0: 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
d400: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
d410: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
d420: 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
d430: 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
d440: 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ter.  It returns
d450: 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
d460: 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
d470: 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
d480: 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
d490: 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63 61  .** After the ca
d4a0: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68  lling function h
d4b0: 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
d4c0: 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74  g the result, it
d4d0: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73   should .** pass
d4e0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
d4f0: 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
d500: 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
d510: 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
d520: 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65  r to .** release
d530: 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
d540: 20 77 61 73 20 6d 61 6c 6c 6f 63 2d 65 64 2e 20   was malloc-ed. 
d550: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
d560: 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  way the .** [sql
d570: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
d580: 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
d590: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
d5a0: 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
d5b0: 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
d5c0: 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
d5d0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
d5e0: 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
d5f0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72   .** [sqlite3_fr
d600: 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
d610: 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
d620: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
d630: 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
d640: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
d650: 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
d660: 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
d670: 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
d680: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
d690: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
d6a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
d6b0: 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
d6c0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
d6d0: 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
d6e0: 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
d6f0: 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
d700: 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
d710: 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
d720: 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
d730: 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
d740: 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
d750: 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
d760: 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
d770: 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
d780: 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
d790: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
d7a0: 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
d7b0: 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
d7c0: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
d7d0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
d7e0: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
d7f0: 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a  _errmsg()]..**.*
d800: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
d810: 0a 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66 20  .** {F12371} If 
d820: 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  a [sqlite3_get_t
d830: 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20  able()] fails a 
d840: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d850: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
d860: 20 20 20 20 69 74 20 66 72 65 65 73 20 74 68 65      it frees the
d870: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e   result table un
d880: 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e  der construction
d890: 2c 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20  , aborts the.** 
d8a0: 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69           query i
d8b0: 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 73  n process, skips
d8c0: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
d8d0: 71 75 65 72 69 65 73 2c 20 73 65 74 73 20 74 68  queries, sets th
d8e0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 72  e.**          *r
d8f0: 65 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70 6f  esultp output po
d900: 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e  inter to NULL an
d910: 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  d returns [SQLIT
d920: 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
d930: 7b 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 20  {F12373} If the 
d940: 6e 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65  ncolumn paramete
d950: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
d960: 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
d970: 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
d980: 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
d990: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72  _get_table()] wr
d9a0: 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ite the number o
d9b0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
d9c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
d9d0: 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
d9e0: 75 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75  uery into *ncolu
d9f0: 6d 6e 20 69 66 20 74 68 65 20 71 75 65 72 79 20  mn if the query 
da00: 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  is.**          s
da10: 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68  uccessful (if th
da20: 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
da30: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a  ns SQLITE_OK)..*
da40: 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49 66  *.** {F12374} If
da50: 20 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d 65   the nrow parame
da60: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
da70: 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  get_table()] is 
da80: 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  not NULL.**     
da90: 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
daa0: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
dab0: 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72  write the number
dac0: 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a   of rows in the.
dad0: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
dae0: 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75  lt set of the qu
daf0: 65 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69  ery into *nrow i
db00: 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a  f the query is.*
db10: 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65  *          succe
db20: 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75  ssful (if the fu
db30: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53  nction returns S
db40: 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a  QLITE_OK)..**.**
db50: 20 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b 73   {F12376} The [s
db60: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
db70: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  ()] function set
db80: 73 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76  s its *ncolumn v
db90: 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
dba0: 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
dbb0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
dbc0: 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
dbd0: 68 65 20 71 75 65 72 79 20 69 6e 20 74 68 65 0a  he query in the.
dbe0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 20  **          sql 
dbf0: 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f  parameter, or to
dc00: 20 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75 65   zero if the que
dc10: 72 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61 6e  ry in sql has an
dc20: 20 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20   empty.**       
dc30: 20 20 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a     result set..*
dc40: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
dc50: 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
dc60: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
dc70: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
dc80: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
dc90: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
dca0: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
dcb0: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
dcc0: 20 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20 20   ***pResult,    
dcd0: 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
dce0: 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
dcf0: 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20 20  nt *nrow,       
dd00: 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
dd10: 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
dd20: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
dd30: 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20  int *ncolumn,   
dd40: 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
dd50: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
dd60: 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
dd70: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
dd80: 67 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72  g         /* Err
dd90: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
dda0: 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
ddb0: 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
ddc0: 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
ddd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
dde0: 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
ddf0: 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
de00: 63 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d 0a  ctions {F17400}.
de10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
de20: 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69  ines are workali
de30: 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
de40: 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
de50: 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
de60: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
de70: 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
de80: 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
de90: 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
dea0: 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
deb0: 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
dec0: 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
ded0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
dee0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
def0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
df00: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
df10: 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
df20: 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
df30: 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
df40: 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
df50: 29 5d 2e 20 20 20 42 6f 74 68 20 72 6f 75 74 69  )].   Both routi
df60: 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
df70: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
df80: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
df90: 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
dfa0: 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
dfb0: 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
dfc0: 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
dfd0: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
dfe0: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
dff0: 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
e000: 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
e010: 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
e020: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
e030: 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
e040: 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
e050: 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
e060: 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
e070: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
e080: 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
e090: 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
e0a0: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
e0b0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
e0c0: 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
e0d0: 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
e0e0: 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
e0f0: 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
e100: 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
e110: 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
e120: 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
e130: 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
e140: 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
e150: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
e160: 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
e170: 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
e180: 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
e190: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
e1a0: 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
e1b0: 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
e1c0: 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
e1d0: 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
e1e0: 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
e1f0: 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
e200: 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
e210: 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
e220: 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
e230: 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
e240: 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
e250: 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
e260: 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
e270: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
e280: 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
e290: 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
e2a0: 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
e2b0: 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
e2c0: 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
e2d0: 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
e2e0: 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
e2f0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
e300: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
e310: 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
e320: 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
e330: 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
e340: 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
e350: 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
e360: 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
e370: 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
e380: 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
e390: 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
e3a0: 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
e3b0: 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
e3c0: 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
e3d0: 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
e3e0: 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
e3f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
e400: 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
e410: 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
e420: 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
e430: 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
e440: 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
e450: 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
e460: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
e470: 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
e480: 72 69 6e 74 66 20 66 6f 72 6d 61 74 74 69 6e 67  rintf formatting
e490: 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
e4a0: 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
e4b0: 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
e4c0: 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
e4d0: 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
e4e0: 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  * The %q option 
e4f0: 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
e500: 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
e510: 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d  utes a null-term
e520: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
e530: 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
e540: 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
e550: 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
e560: 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
e570: 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
e580: 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
e590: 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
e5a0: 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c  teral.  By doubl
e5b0: 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
e5c0: 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
e5d0: 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
e5e0: 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
e5f0: 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
e600: 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
e610: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
e620: 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65  example, so some
e630: 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
e640: 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
e650: 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
e660: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
e670: 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
e680: 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
e690: 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
e6a0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
e6b0: 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
e6c0: 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
e6d0: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
e6e0: 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
e6f0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
e700: 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
e710: 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
e720: 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
e730: 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
e740: 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
e750: 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
e760: 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
e770: 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
e780: 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
e790: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
e7a0: 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
e7b0: 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
e7c0: 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
e7d0: 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
e7e0: 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
e7f0: 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
e800: 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
e810: 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
e820: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
e830: 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
e840: 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
e850: 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
e860: 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
e870: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
e880: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
e890: 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
e8a0: 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
e8b0: 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
e8c0: 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
e8d0: 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
e8e0: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
e8f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
e900: 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
e910: 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
e920: 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
e930: 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
e940: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
e950: 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
e960: 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
e970: 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
e980: 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
e990: 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20  e you.** should 
e9a0: 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
e9b0: 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
e9c0: 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
e9d0: 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a  into a string .*
e9e0: 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  * literal..**.**
e9f0: 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77   The %Q option w
ea00: 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
ea10: 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
ea20: 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
ea30: 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
ea40: 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
ea50: 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66  l string.  Or if
ea60: 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
ea70: 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  n the argument.*
ea80: 2a 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  * list is a NULL
ea90: 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
eaa0: 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
eab0: 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
eac0: 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74  t single.** quot
ead0: 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  es) in place of 
eae0: 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b  the %Q option. {
eaf0: 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78  END}  So, for ex
eb00: 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
eb10: 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
eb20: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
eb30: 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
eb40: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
eb50: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
eb60: 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
eb70: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
eb80: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
eb90: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
eba0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
ebb0: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
ebc0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
ebd0: 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
ebe0: 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
ebf0: 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
ec00: 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
ec10: 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
ec20: 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
ec30: 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
ec40: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ec50: 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
ec60: 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
ec70: 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25   exactly like "%
ec80: 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  s" with the.** a
ec90: 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
eca0: 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
ecb0: 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
ecc0: 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
ecd0: 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
ece0: 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
ecf0: 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
ed00: 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d  ut string. {END}
ed10: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
ed20: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33  S:.**.** {F17403
ed30: 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
ed40: 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b  mprintf()] and [
ed50: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
ed60: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
ed70: 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
ed80: 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65  rn either pointe
ed90: 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
eda0: 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
edb0: 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20  ngs held in.**  
edc0: 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
edd0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
ede0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
edf0: 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   or NULL pointer
ee00: 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s if.**         
ee10: 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    a call to [sql
ee20: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
ee30: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ails..**.** {F17
ee40: 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  406}  The [sqlit
ee50: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
ee60: 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
ee70: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
ee80: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55  d.**           U
ee90: 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f  TF-8 string into
eea0: 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e   the buffer poin
eeb0: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65  ted to by the se
eec0: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
eed0: 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76  *           prov
eee0: 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69  ided that the fi
eef0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
ef00: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
ef10: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30  ro..**.** {F1740
ef20: 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  7}  The [sqlite3
ef30: 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
ef40: 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
ef50: 77 72 69 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a  writes slots of.
ef60: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73  **           its
ef70: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28   output buffer (
ef80: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
ef90: 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68  eter) outside th
efa0: 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20  e range.**      
efb0: 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67       of 0 throug
efc0: 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69  h N-1 (where N i
efd0: 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
efe0: 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20  meter).**       
eff0: 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f      regardless o
f000: 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  f the length of 
f010: 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  the string.**   
f020: 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65          requeste
f030: 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20  d by the format 
f040: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
f050: 2a 20 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  *   .*/.char *sq
f060: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
f070: 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
f080: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
f090: 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
f0a0: 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
f0b0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
f0c0: 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
f0d0: 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
f0e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f0f0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
f100: 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b  tion Subsystem {
f110: 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17300}.**.** Th
f120: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75  e SQLite core  u
f130: 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
f140: 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
f150: 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
f160: 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
f170: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
f180: 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
f190: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
f1a0: 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
f1b0: 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
f1c0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
f1d0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
f1e0: 6e 2e 20 20 54 68 65 0a 2a 2a 20 77 69 6e 64 6f  n.  The.** windo
f1f0: 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
f200: 76 65 20 6d 61 6c 6c 6f 63 20 61 6e 64 20 66 72  ve malloc and fr
f210: 65 65 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  ee for some oper
f220: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ations..**.** Th
f230: 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
f240: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
f250: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
f260: 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
f270: 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
f280: 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
f290: 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
f2a0: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66  parameter..** If
f2b0: 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
f2c0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
f2d0: 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
f2e0: 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
f2f0: 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
f300: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
f310: 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
f320: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
f330: 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
f340: 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
f350: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f360: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
f370: 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
f380: 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  * Calling sqlite
f390: 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
f3a0: 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
f3b0: 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
f3c0: 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
f3d0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
f3e0: 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
f3f0: 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
f400: 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
f410: 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65   be reused.  The
f420: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
f430: 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
f440: 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
f450: 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
f460: 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
f470: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
f480: 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
f490: 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
f4a0: 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
f4b0: 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
f4c0: 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
f4d0: 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
f4e0: 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
f4f0: 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
f500: 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
f510: 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
f520: 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
f530: 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
f540: 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
f550: 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
f560: 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
f570: 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
f580: 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
f590: 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
f5a0: 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
f5b0: 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
f5c0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
f5d0: 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
f5e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
f5f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
f600: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e   sqlite3_free().
f610: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f620: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
f630: 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
f640: 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
f650: 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
f660: 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
f670: 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
f680: 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
f690: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
f6a0: 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
f6b0: 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
f6c0: 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
f6d0: 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
f6e0: 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  r.  If the first
f6f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
f700: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
f710: 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
f720: 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
f730: 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
f740: 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
f750: 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
f760: 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
f770: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
f780: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
f790: 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20  ealloc()..** If 
f7a0: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
f7b0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
f7c0: 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
f7d0: 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
f7e0: 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
f7f0: 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
f800: 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
f810: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
f820: 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
f830: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
f840: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
f850: 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c  ealloc()..** Sql
f860: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
f870: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
f880: 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
f890: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
f8a0: 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
f8b0: 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
f8c0: 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
f8d0: 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
f8e0: 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74  le..** If M is t
f8f0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
f900: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
f910: 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
f920: 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
f930: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
f940: 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
f950: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
f960: 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
f970: 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
f980: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
f990: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
f9a0: 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49  n is freed..** I
f9b0: 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
f9c0: 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
f9d0: 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
f9e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
f9f0: 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
fa00: 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  ** The memory re
fa10: 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
fa20: 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
fa30: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
fa40: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
fa50: 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
fa60: 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
fa70: 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  dary. {END}.**.*
fa80: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d  * The default im
fa90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
faa0: 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  of the memory al
fab0: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
fac0: 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c  em uses the mall
fad0: 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a  oc(), realloc().
fae0: 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72  ** and free() pr
faf0: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74  ovided by the st
fb00: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
fb10: 2e 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76  . {F17382} Howev
fb20: 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74  er, if .** SQLit
fb30: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
fb40: 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  th the following
fb50: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
fb60: 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  macro.**.** <blo
fb70: 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f  ckquote> SQLITE_
fb80: 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e  MEMORY_SIZE=<i>N
fb90: 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75  NN</i> </blockqu
fba0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65  ote>.**.** where
fbb0: 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61   <i>NNN</i> is a
fbc0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20  n integer, then 
fbd0: 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
fbe0: 73 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20  static.** array 
fbf0: 6f 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e  of at least <i>N
fc00: 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
fc10: 73 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61  size and use tha
fc20: 74 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61  t array.** for a
fc30: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
fc40: 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
fc50: 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
fc60: 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20    Additional.** 
fc70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
fc80: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
fc90: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
fca0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
fcb0: 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
fcc0: 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
fcd0: 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
fce0: 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
fcf0: 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
fd00: 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
fd10: 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
fd20: 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
fd30: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fd40: 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
fd50: 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
fd60: 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
fd70: 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
fd80: 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
fd90: 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
fda0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
fdb0: 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a  can be.** used..
fdc0: 2a 2a 0a 2a 2a 20 54 68 65 20 77 69 6e 64 6f 77  **.** The window
fdd0: 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
fde0: 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
fdf0: 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
fe00: 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
fe10: 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
fe20: 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
fe30: 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
fe40: 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
fe50: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
fe60: 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
fe70: 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
fe80: 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
fe90: 72 74 69 63 75 6c 61 72 20 77 69 6e 64 6f 77 73  rticular windows
fea0: 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
feb0: 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
fec0: 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
fed0: 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
fee0: 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
fef0: 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
ff00: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
ff10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
ff20: 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
ff30: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
ff40: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
ff50: 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20  **.** {F17303}  
ff60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
ff70: 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
ff80: 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
ff90: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a   a pointer to .*
ffa0: 2a 20 20 20 20 20 20 20 20 20 20 20 6e 65 77 6c  *           newl
ffb0: 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c  y checked-out bl
ffc0: 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ock of at least 
ffd0: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
ffe0: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  y.**           t
fff0: 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
10000 69 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20  igned, .**      
10010 20 20 20 20 20 6f 72 20 69 74 20 72 65 74 75 72       or it retur
10020 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73  ns NULL if it is
10030 20 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 69   unable to fulfi
10040 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a  ll the request..
10050 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20  **.** {F17304}  
10060 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
10070 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
10080 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
10090 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20   pointer if.**  
100a0 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65           N is le
100b0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
100c0 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   to zero..**.** 
100d0 7b 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73  {F17305}  The [s
100e0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20  qlite3_free(P)] 
100f0 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73  interface releas
10100 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f  es memory previo
10110 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
10120 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20    returned from 
10130 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10140 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
10150 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
10160 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69          making i
10170 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  t available for 
10180 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  reuse..**.** {F1
10190 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7306}  A call to
101a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e   [sqlite3_free(N
101b0 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c  ULL)] is a harml
101c0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
101d0 20 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c   {F17310}  A cal
101e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
101f0 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65  alloc(0,N)] is e
10200 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
10210 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
10220 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
10230 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  loc(N)]..**.** {
10240 46 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20  F17312}  A call 
10250 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
10260 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75  loc(P,0)] is equ
10270 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
10280 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
10290 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
102a0 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  P)]..**.** {F173
102b0 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20  15}  The SQLite 
102c0 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74  core uses [sqlit
102d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
102e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
102f0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
10300 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  and [sqlite3_fre
10310 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e()] for all of 
10320 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  its memory alloc
10330 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ation and.**    
10340 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74         deallocat
10350 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ion needs..**.**
10360 20 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b   {F17318}  The [
10370 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
10380 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,N)] interface 
10390 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
103a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
103b0 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b        to a block
103c0 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20   of checked-out 
103d0 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
103e0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
103f0 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ze.**           
10400 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
10410 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c  ligned, or a NUL
10420 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
10430 20 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20   {F17321}  When 
10440 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10450 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (P,N)] returns a
10460 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
10470 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20  r, it first.**  
10480 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20           copies 
10490 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65  the first K byte
104a0 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f  s of content fro
104b0 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77  m P into the new
104c0 6c 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20  ly allocated.** 
104d0 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
104e0 4b 20 69 73 20 74 68 65 20 6c 65 73 73 6f 72 20  K is the lessor 
104f0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
10500 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
10510 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32  P..**.** {F17322
10520 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
10530 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
10540 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
10550 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
10560 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
10570 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75   releases the bu
10580 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ffer P..**.** {F
10590 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71  17323}  When [sq
105a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
105b0 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  N)] returns NULL
105c0 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69  , the buffer P i
105d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
105e0 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72  ot modified or r
105f0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c  eleased..**.** L
10600 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
10610 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20  * {U17350}  The 
10620 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
10630 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
10640 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
10650 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
10660 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20             must 
10670 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
10680 72 20 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 72  r else a pointer
10690 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
106a0 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
106b0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f      invocation o
106c0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
106d0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
106e0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
106f0 20 68 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   has.**         
10700 20 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 61    not been relea
10710 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33  sed..**.** {U173
10720 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61  51}  The applica
10730 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
10740 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
10750 70 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20  part of .**     
10760 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
10770 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
10780 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
10790 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
107a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
107b0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
107c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
107d0 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  *.*/.void *sqlit
107e0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
107f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
10800 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
10810 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
10820 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
10830 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10840 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
10850 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37  tatistics {F1737
10860 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
10870 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
10880 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
10890 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
108a0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
108b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
108c0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
108d0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
108e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
108f0 5d 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ].** the memory 
10900 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
10910 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69  stem included wi
10920 74 68 69 6e 20 74 68 65 20 53 51 4c 69 74 65 2e  thin the SQLite.
10930 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
10940 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31  S:.**.** {F17371
10950 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
10960 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
10970 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
10980 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
10990 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
109a0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
109b0 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a  y outstanding .*
109c0 2a 20 20 20 20 20 20 20 20 20 20 28 6d 61 6c 6c  *          (mall
109d0 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
109e0 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ed)..**.** {F173
109f0 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
10a00 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
10a10 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
10a20 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
10a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
10a40 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
10a50 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a  emory_used()] .*
10a60 2a 20 20 20 20 20 20 20 20 20 20 73 69 6e 63 65  *          since
10a70 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d   the highwater m
10a80 61 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65 73  ark was last res
10a90 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  et..**.** {F1737
10aa0 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65  4} The values re
10ab0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
10ac0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
10ad0 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
10ae0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
10af0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
10b00 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
10b10 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ead.**          
10b20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
10b30 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
10b40 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
10b50 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
10b60 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74           but not
10b70 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
10b80 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
10b90 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
10ba0 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  rary.**         
10bb0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
10bc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10bd0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20 0a  ] may call..** .
10be0 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65 20  ** {F17375} The 
10bf0 6d 65 6d 6f 72 79 20 68 69 67 68 77 61 74 65 72  memory highwater
10c00 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
10c10 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
10c20 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
10c30 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
10c40 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
10c50 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
10c60 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
10c70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10c80 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
10c90 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68  ()] is true.  Th
10ca0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
10cc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
10cd0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
10ce0 20 74 68 65 20 68 69 67 68 77 61 74 65 72 20 6d   the highwater m
10cf0 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
10d00 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
10d10 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
10d20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
10d30 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
10d40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
10d50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10d60 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
10d70 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
10d80 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
10d90 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
10da0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
10db0 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2500}.**.** This
10dc0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
10dd0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
10de0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
10df0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 64 61  particular.** da
10e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10e10 6e 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  n, supplied in t
10e20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10e30 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  t..** The author
10e40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
10e50 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
10e60 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
10e70 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
10e80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
10e90 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
10ea0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
10eb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
10ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
10ed0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
10ee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
10ef0 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f  v2()].  At vario
10f00 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
10f10 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
10f20 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
10f30 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
10f40 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
10f50 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
10f60 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
10f70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
10f80 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
10f90 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
10fa0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
10fb0 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72    The authorizer
10fc0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
10fd0 0a 2a 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 54  .** return SQLIT
10fe0 45 5f 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68  E_OK to allow th
10ff0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
11000 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
11010 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
11020 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
11030 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
11040 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
11050 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
11060 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
11070 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
11080 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
11090 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
110a0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
110b0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 20 49 66  h an error.   If
110c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
110d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
110e0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
110f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
11100 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
11110 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
11120 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
11130 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11140 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
11150 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
11160 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
11170 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
11180 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
11190 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
111a0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
111b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
111c0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
111d0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
111e0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
111f0 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20  s ok.  When the 
11200 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
11210 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
11220 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
11230 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
11240 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
11250 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
11260 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
11270 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
11280 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
11290 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
112a0 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
112b0 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61  enied.  If the a
112c0 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69  uthorizer code i
112d0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
112e0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
112f0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
11300 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
11310 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
11320 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
11330 6e 73 74 72 75 63 74 65 64 20 74 6f 20 69 6e 73  nstructed to ins
11340 65 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  ert a NULL value
11350 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
11360 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
11370 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
11380 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
11390 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
113a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
113b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
113c0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
113d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
113e0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
113f0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
11400 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
11410 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
11420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
11430 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
11440 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
11450 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
11460 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  of.** the third 
11470 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
11480 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
11490 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
114a0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ace..** The seco
114b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
114c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
114d0 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b  an integer .** [
114e0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
114f0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
11500 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
11510 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
11520 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  ** to be authori
11530 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74  zed. The third t
11540 68 72 6f 75 67 68 20 73 69 78 74 68 0a 2a 2a 20  hrough sixth.** 
11550 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
11560 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
11570 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
11580 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
11590 61 69 6e 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e  ain .** addition
115a0 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  al details about
115b0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
115c0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
115d0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
115e0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 70  r is used when p
115f0 72 65 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61  reparing SQL sta
11600 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
11610 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75  untrusted.** sou
11620 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
11630 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
11640 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72  ements do not tr
11650 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
11660 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20 61 72  .** that they ar
11670 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
11680 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
11690 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ey do not try to
116a0 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69  .** execute mali
116b0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
116c0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
116d0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
116e0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
116f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
11700 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
11710 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
11720 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
11730 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
11740 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
11750 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
11760 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
11770 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
11780 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
11790 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
117a0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
117b0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
117c0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
117d0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
117e0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
117f0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
11800 65 69 6e 67 20 70 72 65 70 61 72 65 64 20 74 68  eing prepared th
11810 61 74 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  at disallows eve
11820 72 79 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70  rything.** excep
11830 74 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  t SELECT stateme
11840 6e 74 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 4f 6e 6c  nts.  .**.** Onl
11850 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
11860 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
11870 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
11880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
11890 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
118a0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
118b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
118c0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
118d0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
118e0 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61  .  Disable the a
118f0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
11900 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
11910 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
11920 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
11930 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
11940 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  t..**.** Note th
11950 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
11960 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
11970 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
11980 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  g .** [sqlite3_p
11990 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
119a0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
119b0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
119c0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
119d0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
119e0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
119f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
11a00 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
11a10 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20  .**.** {F12501} 
11a20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
11a30 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
11a40 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
11a50 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
11a60 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
11a70 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
11a80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11a90 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  on D..**.** {F12
11aa0 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
11ab0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
11ac0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
11ad0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
11ae0 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
11af0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a 2a 20 7b  compiled.**.** {
11b00 46 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61  F12503} If the a
11b10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11b20 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76  ck returns any v
11b30 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a  alue other than.
11b40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
11b50 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
11b60 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
11b70 4c 49 54 45 5f 44 45 4e 59 5d 20 74 68 65 6e 0a  LITE_DENY] then.
11b80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
11b90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
11ba0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
11bb0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
11bc0 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
11bd0 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
11be0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
11bf0 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
11c00 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
11c10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
11c20 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
11c30 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
11c40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
11c50 2a 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20  * {F12504} When 
11c60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
11c70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
11c80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
11c90 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
11ca0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
11cb0 20 69 73 20 63 6f 64 65 64 20 6e 6f 72 6d 61 6c   is coded normal
11cc0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  ly..**.** {F1250
11cd0 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68  5} When the auth
11ce0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
11cf0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
11d00 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20  DENY], the.**   
11d10 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
11d20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
11d30 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
11d40 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
11d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
11d60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11d70 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
11d80 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  il.**          w
11d90 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45  ith an [SQLITE_E
11da0 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
11db0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
11dc0 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
11dd0 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61    explaining tha
11de0 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  t access is deni
11df0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  ed..**.** {F1250
11e00 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  6} If the author
11e10 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
11e20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
11e30 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
11e40 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
11e50 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f  ack) is [SQLITE_
11e60 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75  READ] and the au
11e70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
11e80 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  k returns.**    
11e90 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
11ea0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 70  NORE] then the p
11eb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11ec0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
11ed0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
11ee0 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
11ef0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
11f00 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
11f10 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
11f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65  .**          bee
11f30 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
11f40 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
11f50 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
11f60 46 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61  F12507} If the a
11f70 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
11f80 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
11f90 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
11fa0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
11fb0 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79  callback) is any
11fc0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
11fd0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20   [SQLITE_READ], 
11fe0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
11ff0 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51   a return of [SQ
12000 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73  LITE_IGNORE] has
12010 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74   the same effect
12020 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   as [SQLITE_DENY
12030 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31  ]. .**.** {F1251
12040 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  0} The first par
12050 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
12060 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
12070 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
12080 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
12090 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
120a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
120b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
120c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
120d0 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73  * {F12511} The s
120e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
120f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
12100 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a  is an integer .*
12110 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
12120 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
12130 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
12140 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63  ifies the partic
12150 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  ular action.**  
12160 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75          to be au
12170 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
12180 7b 46 31 32 35 31 32 7d 20 54 68 65 20 74 68 69  {F12512} The thi
12190 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
121a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
121b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a  he callback are.
121c0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
121d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
121e0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
121f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64   .**          ad
12200 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
12210 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
12220 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
12230 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  ed..**.** {F1252
12240 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  0} Each call to 
12250 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12260 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72  horizer()] overr
12270 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ides the.**     
12280 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75       any previou
12290 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75  sly installed au
122a0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
122b0 7b 46 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20  {F12521} A NULL 
122c0 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
122d0 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
122e0 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  zation.**       
122f0 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69     callback is i
12300 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
12310 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75  12522} The defau
12320 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  lt authorizer is
12330 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
12340 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
12350 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
12360 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
12370 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
12380 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
12390 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
123a0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
123b0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
123c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
123d0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
123e0 74 75 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35  turn Codes {F125
123f0 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  90}.**.** The [s
12400 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
12410 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
12420 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
12430 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
12440 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
12450 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
12460 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
12470 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
12480 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
12490 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
124a0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
124b0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
124c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
124d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
124e0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
124f0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
12500 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
12510 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
12520 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
12530 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
12540 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
12550 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
12560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12570 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
12580 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
12590 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
125a0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
125b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
125c0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
125d0 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32  ction Codes {F12
125e0 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  550}.**.** The [
125f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
12600 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
12610 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
12620 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
12630 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
12640 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
12650 65 72 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  er certain SQL s
12660 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
12670 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
12680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
12690 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
126a0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
126b0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
126c0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
126d0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
126e0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
126f0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
12700 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
12710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
12720 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
12730 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
12740 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
12750 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
12760 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
12770 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a 2a 20 61  n is to be .** a
12780 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
12790 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
127a0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
127b0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
127c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
127d0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
127e0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
127f0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
12800 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
12810 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
12820 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12830 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
12840 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
12850 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
12860 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
12870 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
12880 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
12890 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
128a0 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74  licable.  The 6t
128b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
128c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
128d0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
128e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
128f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
12900 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
12910 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
12920 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
12930 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
12940 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
12950 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
12960 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70 2d 6c 65   from .** top-le
12970 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a  vel SQL code..**
12980 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
12990 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20 54  **.** {F12551} T
129a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
129b0 74 65 72 20 74 6f 20 61 6e 20 0a 2a 2a 20 20 20  ter to an .**   
129c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
129d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
129e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
129f0 62 61 63 6b 20 69 73 20 61 6c 77 61 79 73 20 61  back is always a
12a00 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
12a10 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
12a20 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
12a30 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
12a40 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e  fies what action
12a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
12a60 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
12a70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32 7d  ..**.** {F12552}
12a80 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
12a90 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
12aa0 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
12ab0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
12ac0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
12ad0 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
12ae0 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20   function].**   
12af0 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70         will be p
12b00 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
12b10 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
12b20 68 69 63 68 20 0a 2a 2a 20 20 20 20 20 20 20 20  hich .**        
12b30 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
12b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
12b50 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  ] is used as the
12b60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12b70 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33  r..**.** {F12553
12b80 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  } The 5th parame
12b90 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
12ba0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
12bb0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
12bc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
12bd0 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
12be0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
12bf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65   the database (e
12c00 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20  xample: "main", 
12c10 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66  "temp", etc.) if
12c20 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a   applicable..**.
12c30 2a 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20  ** {F12554} The 
12c40 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
12c50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
12c60 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
12c70 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
12c80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
12c90 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  is the name.**  
12ca0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69          of the i
12cb0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
12cc0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
12cd0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12ce0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
12cf0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
12d00 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
12d10 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
12d20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
12d30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f   .**          to
12d40 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
12d50 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
12d60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12d80 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
12d90 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
12da0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
12db0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
12dc0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
12dd0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
12de0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
12df0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12e00 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
12e10 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
12e20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
12e30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
12e40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12e50 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
12e60 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
12e70 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
12e80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
12e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12ea0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
12eb0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
12ec0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
12ed0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
12ee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12ef0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
12f00 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
12f10 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
12f20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
12f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
12f40 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
12f50 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
12f60 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
12f70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
12f80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
12f90 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
12fa0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
12fb0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
12fc0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
12fd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
12fe0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
12ff0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
13000 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
13010 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13020 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
13030 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
13040 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
13050 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
13060 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13070 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
13080 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
13090 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
130a0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
130b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
130c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
130d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
130e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
130f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
13100 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13110 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
13120 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
13130 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
13140 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
13150 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13160 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
13170 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
13180 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13190 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
131a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
131b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
131c0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
131d0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
131e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
131f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
13200 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
13210 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
13220 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
13230 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13240 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13250 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
13260 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
13270 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
13280 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
13290 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
132a0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
132b0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
132c0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
132d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
132e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
132f0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
13300 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
13310 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
13320 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
13330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13340 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
13350 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
13360 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
13370 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
13380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13390 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
133a0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
133b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
133c0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
133d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
133e0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
133f0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
13400 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
13410 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
13420 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
13430 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
13440 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
13450 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
13460 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
13470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
13480 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
13490 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
134a0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
134b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
134c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
134d0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
134e0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
134f0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
13500 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
13510 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
13520 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
13530 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
13540 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
13550 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
13560 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
13570 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
13580 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
13590 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
135a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
135b0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
135c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
135d0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
135e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
135f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
13600 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
13610 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
13620 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
13630 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
13640 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
13650 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
13660 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
13670 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
13680 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
13690 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
136a0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
136b0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
136c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
136d0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
136e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
136f0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
13700 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
13710 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
13720 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
13730 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
13740 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
13750 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
13760 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
13770 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
13780 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
13790 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
137a0 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a  ons {F12280}.**.
137b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
137c0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
137d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
137e0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
137f0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
13800 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
13810 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
13820 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
13830 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
13840 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
13850 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
13860 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
13870 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
13880 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
13890 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
138a0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
138b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
138c0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   The callback re
138d0 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65  turns a UTF-8 re
138e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53  ndering of the S
138f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
13900 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74  t.** as the stat
13910 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
13920 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41  ns executing.  A
13930 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
13940 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  cks occur.** as 
13950 65 61 63 68 20 74 72 69 67 67 65 72 73 75 62 70  each triggersubp
13960 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
13970 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
13980 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
13990 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
139a0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
139b0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
139c0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a  e trigger..** .*
139d0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
139e0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
139f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
13a00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
13a10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
13a20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
13a30 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69  shes.  The profi
13a40 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
13a50 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
13a60 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
13a70 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
13a80 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
13a90 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
13aa0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
13ab0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
13ac0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
13ad0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50  te3_profile() AP
13ae0 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  I is currently c
13af0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
13b00 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73  mental and.** is
13b10 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
13b20 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e  ge or removal in
13b30 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
13b40 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69  e..**.** The tri
13b50 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66  gger reporting f
13b60 65 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72  eature of the tr
13b70 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
13b80 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78  considered.** ex
13b90 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
13ba0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
13bb0 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69  nge or removal i
13bc0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
13bd0 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72  s..** Future ver
13be0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
13bf0 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e  might also add n
13c00 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ew trace callbac
13c10 6b 20 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  k .** invocation
13c20 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
13c30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
13c40 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  81} The callback
13c50 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
13c60 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
13c70 5f 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20  _trace()] is.** 
13c80 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
13c90 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  r an SQL stateme
13ca0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
13cb0 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a  to execute and.*
13cc0 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65  *          whene
13cd0 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75  ver a trigger su
13ce0 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62  bprogram first b
13cf0 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a  egins to run..**
13d00 0a 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 63  .** {F12282} Eac
13d10 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
13d20 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72  e3_trace()] over
13d30 72 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f  rides the previo
13d40 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
13d50 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63   registered trac
13d60 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
13d70 2a 20 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 4c  * {F12283} A NUL
13d80 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  L trace callback
13d90 20 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e   disables tracin
13da0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34  g..**.** {F12284
13db0 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
13dc0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
13dd0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
13de0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
13df0 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20      the pointer 
13e00 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72  which was the 3r
13e10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  d argument to [s
13e20 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e  qlite3_trace()].
13e30 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20  .**.** {F12285} 
13e40 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
13e50 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
13e60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a   callback is a.*
13e70 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
13e80 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20  terminated UTF8 
13e90 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
13ea0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  g the original t
13eb0 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
13ec0 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
13ed0 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
13ee0 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69  assed into [sqli
13ef0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
13f00 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
13f10 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c   the equivalent,
13f20 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
13f30 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  nt indicating th
13f40 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20  e beginning.**  
13f50 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69          of a tri
13f60 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
13f70 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20  .**.** {F12287} 
13f80 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
13f90 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
13fa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   by [sqlite3_pro
13fb0 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b  file()] is invok
13fc0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ed.**          a
13fd0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
13fe0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
13ff0 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68  *.** {F12288} Th
14000 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14010 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
14020 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
14030 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
14040 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d     the 3rd param
14050 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
14060 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a  _profile()]..**.
14070 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20  ** {F12289} The 
14080 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14090 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
140a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
140b0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
140c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
140d0 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74  string that cont
140e0 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  ains the complet
140f0 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20  e text of.**    
14100 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74        the SQL st
14110 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
14120 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b  s processed by [
14130 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
14140 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
14150 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
14160 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ent..**.** {F122
14170 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61  90} The third pa
14180 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
14190 72 6f 66 69 6c 65 20 20 63 61 6c 6c 62 61 63 6b  rofile  callback
141a0 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a   is an estimate.
141b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
141c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
141d0 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c  oseconds of wall
141e0 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75  -clock time requ
141f0 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ired to.**      
14200 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20      run the SQL 
14210 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73  statement from s
14220 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a  tart to finish..
14230 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
14240 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
14250 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
14260 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
14270 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
14280 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
14290 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
142a0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
142b0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
142c0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
142d0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
142e0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
142f0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
14300 6b 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a  ks {F12910}.**.*
14310 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
14320 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c  onfigures a call
14330 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20  back function - 
14340 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  the.** progress 
14350 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20  callback - that 
14360 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
14370 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
14380 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63  ong.** running c
14390 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
143a0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
143b0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a  e3_step()] and.*
143c0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
143d0 61 62 6c 65 28 29 5d 2e 20 20 20 41 6e 20 65 78  able()].   An ex
143e0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
143f0 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  is .** interface
14400 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
14410 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
14420 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
14430 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f  **.** If the pro
14440 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
14450 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
14460 20 74 68 65 20 6f 70 65 72 74 69 6f 6e 20 69 73   the opertion is
14470 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
14480 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
14490 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
144a0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
144b0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
144c0 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78  a GUI dialog box
144d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
144e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31  TS:.**.** {F1291
144f0 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
14500 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
14510 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
14520 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
14530 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
14540 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
14550 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
14560 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
14570 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
14580 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
14590 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32  ]..**.** {F12912
145a0 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  } The progress c
145b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
145c0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72  ed once for ever
145d0 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20  y N virtual.**  
145e0 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20          machine 
145f0 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e  opcodes, where N
14600 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14610 72 67 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 20  rgument to .**  
14620 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
14630 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
14640 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68  ndler()] call th
14650 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  at registered.**
14660 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
14670 6c 6c 62 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57  llback.  <todo>W
14680 68 61 74 20 69 66 20 4e 20 69 73 20 6c 65 73 73  hat if N is less
14690 20 74 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a   than 1?</todo>.
146a0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54  **.** {F12913} T
146b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
146c0 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69  back itself is i
146d0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
146e0 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20   third.**       
146f0 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b     argument to [
14700 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
14710 5f 68 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a  _handler()]..**.
14720 2a 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20  ** {F12914} The 
14730 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
14740 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
14750 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 69 73 20  s_handler()] is 
14760 61 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 6f  a.***         vo
14770 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
14780 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
14790 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
147a0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
147b0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
147c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
147d0 46 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c  F12915} If a cal
147e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
147f0 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e  ep()] results in
14800 20 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20   fewer than.**  
14810 20 20 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 65          N opcode
14820 73 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  s being executed
14830 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
14840 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
14850 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65  callback is neve
14860 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d  r invoked. {END}
14870 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d  .** .** {F12916}
14880 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b   Every call to [
14890 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
148a0 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20  _handler()].**  
148b0 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74          overwrit
148c0 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  es any previousl
148d0 79 20 72 65 67 69 73 74 65 72 65 20 70 72 6f 67  y registere prog
148e0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
148f0 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20  .** {F12917} If 
14900 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
14910 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
14920 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72   NULL then no pr
14930 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  ogress.**       
14940 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e     handler is in
14950 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
14960 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f  2918} If the pro
14970 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
14980 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
14990 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68  other than 0, th
149a0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
149b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61  he behavior is a
149c0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   if [sqlite3_int
149d0 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65  errupt()] had be
149e0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f  en called..*/.vo
149f0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
14a00 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
14a10 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
14a20 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
14a30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14a40 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
14a50 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
14a60 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a  tion {F12700}.**
14a70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
14a80 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
14a90 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
14aa0 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73  whose name.** is
14ab0 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69   given by the fi
14ac0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
14ad0 0a 2a 2a 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  .** The filename
14ae0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
14af0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
14b00 38 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65  8.** for [sqlite
14b10 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
14b20 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
14b30 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
14b40 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
14b50 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
14b60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14b70 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  )]..** An [sqlit
14b80 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  e3*] handle is u
14b90 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 65 64 20  sually returned 
14ba0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a  in *ppDb, even.*
14bb0 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * if an error oc
14bc0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
14bd0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 69 66 20  exception is if 
14be0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
14bf0 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  .** to allocate 
14c00 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
14c10 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
14c20 65 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ect, a NULL will
14c30 0a 2a 2a 20 62 65 20 77 72 69 74 74 65 6e 20 69  .** be written i
14c40 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
14c50 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
14c60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  o the [sqlite3] 
14c70 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49 66 20 74 68  object..** If th
14c80 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
14c90 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
14ca0 61 74 65 64 29 0a 2a 2a 20 73 75 63 63 65 73 73  ated).** success
14cb0 66 75 6c 6c 79 2c 20 74 68 65 6e 20 5b 53 51 4c  fully, then [SQL
14cc0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
14cd0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
14ce0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
14cf0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
14d00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
14d10 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
14d20 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
14d30 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62    routines can b
14d40 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
14d50 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
14d60 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
14d70 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
14d80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
14d90 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
14da0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
14db0 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
14dc0 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
14dd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
14de0 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c  pen_v2()] is cal
14df0 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
14e00 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
14e10 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73  byte order if [s
14e20 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
14e30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
14e40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
14e50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
14e60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
14e70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
14e80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
14e90 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  he [sqlite3*] ha
14ea0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
14eb0 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69  eleased by passi
14ec0 6e 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ng it.** to [sql
14ed0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
14ee0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
14ef0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
14f00 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
14f10 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
14f20 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
14f30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
14f40 20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74   .** except that
14f50 20 69 74 20 61 63 63 63 65 70 74 73 20 74 77 6f   it acccepts two
14f60 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
14f70 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
14f80 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
14f90 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
14fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14fb0 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
14fc0 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 0a 2a  rameter can be.*
14fd0 2a 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20  * one of:.**.** 
14fe0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ol>.** <li>  [S
14ff0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
15000 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NLY].** <li>  [S
15010 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
15020 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RITE].** <li>  [
15030 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
15040 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
15050 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a  _OPEN_CREATE].**
15060 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ol>.**.** The
15070 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65   first value ope
15080 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ns the database 
15090 72 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49  read-only. .** I
150a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
150b0 6f 65 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  oes not previous
150c0 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
150d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
150e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70  ** The second op
150f0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68  tion opens.** th
15100 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
15110 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
15120 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
15130 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
15140 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c  if.** if the fil
15150 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
15160 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72  cted.  In either
15170 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
15180 73 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61  se.** must alrea
15190 64 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65  dy exist or an e
151a0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
151b0 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74  .  The third opt
151c0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65  ion.** opens the
151d0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
151e0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
151f0 67 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74  g and creates it
15200 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   if it does.** n
15210 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
15220 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 6f  ..** The third o
15230 70 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76 69  ptions is behavi
15240 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
15250 73 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c 69  s used for [sqli
15260 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61  te3_open()].** a
15270 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
15280 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  16()]..**.** If 
15290 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
152a0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
152b0 20 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 69   an private.** i
152c0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
152d0 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
152e0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
152f0 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79    This in-memory
15300 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c  .** database wil
15310 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68  l vanish when th
15320 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15330 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
15340 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
15350 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ion of SQLite mi
15360 67 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  ght make use of 
15370 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
15380 61 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  al filenames.** 
15390 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
153a0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
153b0 72 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  r.  It is recomm
153c0 65 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77  ended that .** w
153d0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
153e0 69 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64  ilename really d
153f0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
15400 2a 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70  * ":" that you p
15410 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
15420 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
15430 6d 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a  me like "./" to.
15440 2a 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  ** avoid ambigui
15450 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ty..**.** If the
15460 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
15470 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
15480 65 6e 20 61 20 70 72 69 76 61 74 65 20 74 65 6d  en a private tem
15490 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
154a0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
154b0 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69  be created.  Thi
154c0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
154d0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
154e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
154f0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
15500 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
15510 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
15520 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
15530 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
15540 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
15550 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
15560 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
15570 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
15580 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
15590 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a  erating system .
155a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ** interface tha
155b0 74 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  t the new databa
155c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
155d0 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68  ould use.  If th
155e0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
155f0 6d 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20  meter is a NULL 
15600 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
15610 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
15620 33 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  3_vfs].** object
15630 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
15640 3c 62 3e 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f  <b>Note to windo
15650 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
15660 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
15670 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
15680 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
15690 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
156a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
156b0 70 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62  pen_v2()] must b
156c0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
156d0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
156e0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
156f0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
15700 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
15710 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
15720 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
15730 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
15740 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
15750 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
15760 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
15770 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15780 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
15790 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
157a0 0a 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65  .** {F12701} The
157b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
157c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
157d0 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  16()], and.**   
157e0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
157f0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
15800 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e  faces create a n
15810 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
15820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15830 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20  ion] associated 
15840 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
15850 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
15860 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69  le given in thei
15870 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  r first paramete
15880 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32  r..**.** {F12702
15890 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  } The filename a
158a0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
158b0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a  preted as UTF-8.
158c0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
158d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
158e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
158f0 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20  en_v2()] and as 
15900 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20  UTF-16.**       
15910 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65     in the native
15920 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
15930 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15940 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  )]..**.** {F1270
15950 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
15960 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
15970 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
15980 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15990 29 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  )], .**         
159a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
159b0 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61  n_v2()] writes a
159c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
159d0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
159e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
159f0 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a  on] into *ppDb..
15a00 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54  **.** {F12704} T
15a10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
15a20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
15a30 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
15a40 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
15a50 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
15a60 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b  erfaces return [
15a70 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20  SQLITE_OK] upon 
15a80 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20  success,.**     
15a90 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f       or an appro
15aa0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
15ab0 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
15ac0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54  **.** {F12706} T
15ad0 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
15ae0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
15af0 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
15b00 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
15b10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
15b20 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
15b30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69  e3_open_v2()] wi
15b40 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ll be UTF-8..**.
15b50 2a 2a 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20  ** {F12707} The 
15b60 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
15b70 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
15b80 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
15b90 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
15ba0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
15bb0 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  16()] will be UT
15bc0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  F-16..**.** {F12
15bd0 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  709} The [sqlite
15be0 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74  3_open(F,D)] int
15bf0 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
15c00 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  lent to.**      
15c10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
15c20 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77  n_v2(F,D,G,0)] w
15c30 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d  here the G param
15c40 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20  eter is.**      
15c50 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e      [SQLITE_OPEN
15c60 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c  _READWRITE]|[SQL
15c70 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
15c80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d  ..**.** {F12711}
15c90 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
15ca0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
15cb0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
15cc0 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
15cd0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
15ce0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
15cf0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e  N_READONLY] then
15d00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
15d10 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
15d20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20      for reading 
15d30 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  only..**.** {F12
15d40 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61  712} If the G pa
15d50 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
15d60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
15d70 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
15d80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
15d90 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
15da0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
15db0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
15dc0 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
15dd0 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67           reading
15de0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
15df0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72  possible, or for
15e00 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
15e10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15e20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
15e30 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
15e40 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
15e50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d  ..**.** {F12713}
15e60 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
15e70 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
15e80 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29  open(v2(F,D,G,V)
15e90 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20  ] omits the.**  
15ea0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
15eb0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
15ec0 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
15ed0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
15ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
15ef0 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61  viously exist, a
15f00 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
15f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  ned..**.** {F127
15f20 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  14} If the G par
15f30 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15f40 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47  e3_open(v2(F,D,G
15f50 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
15f60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
15f70 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
15f80 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
15f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
15fa0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
15fb0 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
15fc0 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74  ist, then an att
15fd0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
15fe0 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20  create and.**   
15ff0 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a         initializ
16000 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
16010 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49  **.** {F12717} I
16020 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  f the filename a
16030 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
16040 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
16050 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
16060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
16070 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16080 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ()] is ":memory:
16090 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
160a0 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
160b0 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65  ephemeral, in-me
160c0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
160d0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
160e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20   connection..** 
160f0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
16100 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
16110 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
16120 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
16130 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
16140 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
16150 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
16160 2a 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74  ** {F12719} If t
16170 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e  he filename is N
16180 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
16190 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
161a0 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
161b0 20 20 20 20 65 70 68 65 72 6d 65 72 61 6c 20 6f      ephermeral o
161c0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
161d0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
161e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
161f0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
16200 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
16210 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
16220 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
16230 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
16240 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
16250 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20  .**.** {F12721} 
16260 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
16270 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65  nnection] create
16280 64 20 62 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  d by .**        
16290 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
162a0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 77 69 6c  v2(F,D,G,V)] wil
162b0 6c 20 75 73 65 20 74 68 65 0a 2a 2a 20 20 20 20  l use the.**    
162c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
162d0 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74  fs] object ident
162e0 69 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70  ified by the V p
162f0 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
16300 20 20 20 20 20 20 20 20 20 74 68 65 20 64 65 66           the def
16310 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
16320 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 56 20 69  s] object is V i
16330 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16340 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
16350 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
16360 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
16370 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
16380 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
16390 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
163a0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
163b0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
163c0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
163d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
163e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
163f0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
16400 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
16410 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
16420 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
16430 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
16440 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
16450 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
16460 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
16470 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
16480 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
16490 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
164a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
164b0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
164c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
164d0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
164e0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
164f0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
16500 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
16510 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
16520 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
16530 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
16540 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
16550 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
16560 67 65 73 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a  ges {F12800}.**.
16570 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
16580 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
16590 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
165a0 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  umeric.** [SQLIT
165b0 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
165c0 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
165d0 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
165e0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
165f0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73  ].** for the mos
16600 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
16610 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
16620 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
16630 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20   with [sqlite3] 
16640 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 49 66 20  handle 'db'. If 
16650 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
16660 20 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a   failed but the.
16670 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  ** most recent A
16680 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
16690 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
166a0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
166b0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73  _errcode().** is
166c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
166d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
166e0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
166f0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
16700 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
16710 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
16720 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
16730 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
16740 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  r UTF8 or UTF16 
16750 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
16760 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
16770 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
16780 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
16790 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
167a0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
167b0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
167c0 20 74 6f 20 77 6f 72 72 79 20 77 69 74 68 20 66   to worry with f
167d0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
167e0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
167f0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
16800 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
16810 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
16820 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
16830 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
16840 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
16850 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  face functions..
16860 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
16870 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d  :.**.** {F12801}
16880 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
16890 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66  rcode(D)] interf
168a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
168b0 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20  numeric.**      
168c0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c      [SQLITE_OK |
168d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72   result code] or
168e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
168f0 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
16900 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
16910 74 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20  t code].**      
16920 20 20 20 20 66 6f 72 20 74 68 65 20 6d 6f 73 74      for the most
16930 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
16940 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
16950 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
16960 20 20 20 20 20 20 20 77 69 74 68 20 5b 64 61 74         with [dat
16970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16980 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  ] D..**.** {F128
16990 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
169a0 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20  _errmsg(D)] and 
169b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
169c0 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  6(D)].**        
169d0 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
169e0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
169f0 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64  uage text that d
16a00 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20  escribes.**     
16a10 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69       the error i
16a20 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63  n the mostly rec
16a30 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
16a40 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20  erface call,.** 
16a50 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64           encoded
16a60 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20   as either UTF8 
16a70 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74  or UTF16 respect
16a80 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ively..**.** {F1
16a90 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67  2807} The string
16aa0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
16ab0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
16ac0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
16ad0 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
16ae0 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20        are valid 
16af0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53  until the next S
16b00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
16b10 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  call..**.** {F12
16b20 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50  808} Calls to AP
16b30 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  I routines that 
16b40 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e  do not return an
16b50 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
16b60 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65          (example
16b70 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
16b80 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74  count()]) do not
16b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61  .**          cha
16ba0 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f  nge the error co
16bb0 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65  de or message re
16bc0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
16bd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
16be0 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
16bf0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
16c00 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
16c10 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  g16()]..**.** {F
16c20 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65  12809} Interface
16c30 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61  s that are not a
16c40 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
16c50 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20   specific.**    
16c60 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
16c70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61  connection] (exa
16c80 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20  mples:.**       
16c90 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69     [sqlite3_mpri
16ca0 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ntf()] or [sqlit
16cb0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
16cc0 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20  _cache()].**    
16cd0 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61        do not cha
16ce0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72  nge the values r
16cf0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
16d00 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16d10 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c  errcode()], [sql
16d20 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
16d30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
16d40 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
16d50 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
16d60 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
16d70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
16d80 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
16d90 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
16da0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
16db0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
16dd0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
16de0 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45  t {F13000}.** KE
16df0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
16e00 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
16e10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
16e20 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
16e30 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
16e40 65 63 74 20 72 65 70 72 65 73 65 6e 74 20 73 69  ect represent si
16e50 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
16e60 6e 74 73 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 62  nts.  This.** ob
16e70 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
16e80 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
16e90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
16ea0 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70  " or a .** "comp
16eb0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
16ec0 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
16ed0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
16ee0 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  ** .** The life 
16ef0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
16f00 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
16f10 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
16f20 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
16f30 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
16f40 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
16f50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16f60 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
16f70 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
16f80 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
16f90 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
16fa0 61 6d 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a  ameters using.**
16fb0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
16fc0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
16fd0 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66  e3_bind_* interf
16fe0 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  aces]..** <li> R
16ff0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
17000 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
17010 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
17020 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
17030 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
17040 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
17050 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
17060 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
17070 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
17080 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
17090 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
170a0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
170b0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
170c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
170d0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
170e0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
170f0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
17100 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
17110 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
17120 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
17130 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
17140 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
17150 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
17160 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17170 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
17180 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  L Statement {F13
17190 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  010}.**.** To ex
171a0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
171b0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
171c0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
171d0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
171e0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
171f0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
17200 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  tines. .**.** Th
17210 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17220 20 22 64 62 22 20 69 73 20 61 6e 20 5b 64 61 74   "db" is an [dat
17230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17240 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ] .** obtained f
17250 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c 6c  rom a prior call
17260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
17270 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
17280 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20  pen_v2()].** or 
17290 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
172a0 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73 65 63 6f  )]. .** The seco
172b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53 71  nd argument "zSq
172c0 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  l" is the statem
172d0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
172e0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
172f0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
17300 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
17310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
17320 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
17330 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
17340 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54 46  erfaces uses UTF
17350 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  -8 and sqlite3_p
17360 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
17370 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17380 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
17390 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  -16. {END}.**.**
173a0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
173b0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 0a 2a  gument is less.*
173c0 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  * than zero, the
173d0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
173e0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
173f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
17400 2a 2a 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  ** If nByte is n
17410 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
17420 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
17430 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  mum number of .*
17440 2a 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f  * bytes read fro
17450 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
17460 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
17470 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
17480 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
17490 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
174a0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
174b0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
174c0 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e   .** until the n
174d0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
174e0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
174f0 72 73 74 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  rst. {END}.**.**
17500 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
17510 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
17520 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
17530 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a   the end of the.
17540 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  ** first SQL sta
17550 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
17560 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17570 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 73 20 74 68  only compiles th
17580 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65  e first.** state
17590 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
175a0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
175b0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61   pointing to wha
175c0 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63  t remains.** unc
175d0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
175e0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
175f0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
17600 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
17610 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
17620 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
17630 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
17640 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69  3_step()].  Or i
17650 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
17660 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79  ror, *ppStmt may
17670 20 62 65 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55   be.** set to NU
17680 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75  LL.  If the inpu
17690 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
176a0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
176b0 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65  nput.** is and e
176c0 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61  mpty string or a
176d0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
176e0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
176f0 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31   NULL..** {U1301
17700 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  8} The calling p
17710 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
17720 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
17730 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ting the.** comp
17740 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
17750 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  nt.** using [sql
17760 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
17770 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
17780 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
17790 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
177a0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
177b0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
177c0 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72  rwise an .** [er
177d0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
177e0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
177f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
17800 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
17810 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
17820 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
17830 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
17840 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
17850 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
17860 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
17870 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
17880 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
17890 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
178a0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
178b0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74  ouraged..** In t
178c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
178d0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
178e0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
178f0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
17900 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
17910 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
17920 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
17930 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  e .** original S
17940 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54  QL text. {END} T
17950 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
17960 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
17970 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
17980 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65  behave a differe
17990 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73  ntly in two ways
179a0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
179b0 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64  <li>.** If the d
179c0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
179d0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
179e0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
179f0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
17a00 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
17a10 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
17a20 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
17a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
17a40 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
17a50 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
17a60 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
17a70 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68  ain.  If the sch
17a80 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20  ema has changed 
17a90 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74  in.** a way that
17aa0 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65   makes the state
17ab0 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76  ment no longer v
17ac0 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  alid, [sqlite3_s
17ad0 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c  tep()] will stil
17ae0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
17af0 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75  ITE_SCHEMA].  Bu
17b00 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67  t unlike the leg
17b10 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a  acy behavior, .*
17b20 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  * [SQLITE_SCHEMA
17b30 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c  ] is now a fatal
17b40 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
17b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17b60 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
17b70 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
17b80 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
17b90 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
17ba0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
17bb0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
17bc0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
17bd0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
17be0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
17bf0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
17c00 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20  eturn. {END}.** 
17c10 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
17c20 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  .** When an erro
17c30 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73  r occurs, .** [s
17c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
17c50 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
17c60 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a  f the detailed .
17c70 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
17c80 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
17c90 72 6f 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20  ror codes]. .** 
17ca0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
17cb0 69 6f 72 20 77 61 73 20 74 68 61 74 20 5b 73 71  ior was that [sq
17cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
17cd0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
17ce0 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51  a generic.** [SQ
17cf0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
17d00 6c 74 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20  lt code and you 
17d10 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
17d20 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
17d30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
17d40 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
17d50 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
17d60 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
17d70 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a  f the problem..*
17d80 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
17d90 70 72 65 70 61 72 65 20 69 6e 74 65 72 66 61 63  prepare interfac
17da0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
17db0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
17dc0 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65  e error is.** re
17dd0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
17de0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
17df0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
17e00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
17e10 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
17e20 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
17e30 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
17e40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
17e50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
17e60 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
17e70 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
17e80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17e90 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
17ea0 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
17eb0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
17ec0 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
17ed0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
17ee0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
17ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
17f00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
17f10 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
17f20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
17f30 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
17f40 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
17f50 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
17f60 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
17f70 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
17f80 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  rder..**.** {F13
17f90 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
17fa0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
17fb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17fc0 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
17fd0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
17fe0 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
17ff0 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
18000 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74  zero, then SQL t
18010 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ext is.**       
18020 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71     read from zSq
18030 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
18040 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
18050 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
18060 20 7b 46 31 33 30 31 34 7d 20 49 66 20 74 68 65   {F13014} If the
18070 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
18080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
18090 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
180a0 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
180b0 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
180c0 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e  ariants is non-n
180d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 6e 42  egative, then nB
180e0 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 20 20  ytes bytes.**   
180f0 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20         SQL text 
18100 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  is read from zSq
18110 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35  l..**.** {F13015
18120 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  } In [sqlite3_pr
18130 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
18140 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e  ,N,P,pzTail)] an
18150 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  d its variants.*
18160 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
18170 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78  e zSql input tex
18180 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20  t contains more 
18190 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61  than one SQL sta
181a0 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  tement.**       
181b0 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73     and pzTail is
181c0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
181d0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
181e0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a  to point to the.
181f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73  **          firs
18200 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
18210 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
18220 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
18230 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20  n zSql..**      
18240 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64      <todo>What d
18250 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e  oes *pzTail poin
18260 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73  t to if there is
18270 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c   one statement?<
18280 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
18290 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66  3016} A successf
182a0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
182b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
182c0 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c  b,zSql,N,ppStmt,
182d0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
182e0 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20    or one of its 
182f0 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20  variants writes 
18300 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70  into *ppStmt a p
18310 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
18320 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
18330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18340 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
18350 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
18360 20 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69    if zSql contai
18370 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72  ns nothing other
18380 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65   than whitespace
18390 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 20 0a 2a   or comments. .*
183a0 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d 20 54 68  *.** {F13019} Th
183b0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
183c0 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  re_v2()] interfa
183d0 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  ce and its varia
183e0 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  nts return.**   
183f0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
18400 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  K] or an appropr
18410 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
18420 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  ] upon failure..
18430 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
18440 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
18450 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
18460 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
18470 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
18480 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
18490 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
184a0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
184b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
184c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
184d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
184e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
184f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
18500 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
18510 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
18520 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
18530 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
18540 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
18550 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
18560 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
18570 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
18580 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
18590 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
185a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
185b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
185c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
185d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
185e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
185f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
18600 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
18610 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
18620 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
18630 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
18640 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
18650 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
18660 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
18670 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
18680 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
18690 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
186a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
186b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
186c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
186d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
186e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
186f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
18700 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
18710 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
18720 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
18730 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
18740 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
18750 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
18760 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
18770 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
18780 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
18790 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
187a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
187b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
187c0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
187d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
187e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
187f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
18800 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
18810 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
18820 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
18830 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
18840 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
18850 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
18860 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
18870 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
18880 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
18890 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
188a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
188b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
188c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
188d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
188e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
188f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
18900 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
18910 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
18920 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
18930 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
18940 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
18950 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69  * CAPIREF: Retri
18960 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
18970 53 51 4c 20 7b 46 31 33 31 30 30 7d 0a 2a 2a 0a  SQL {F13100}.**.
18980 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 65 66 61  ** This interefa
18990 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
189a0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
189b0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
189c0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
189d0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
189e0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
189f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a  tatement]..**.**
18a00 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
18a10 2a 2a 20 7b 46 31 33 31 30 31 7d 20 49 66 20 74  ** {F13101} If t
18a20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
18a30 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
18a40 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  s .**          t
18a50 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74  he an argument t
18a60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  o [sqlite3_sql()
18a70 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  ] was compiled.*
18a80 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69  *          compi
18a90 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
18aa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18ab0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
18ac0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18ad0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
18ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
18af0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
18b00 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
18b10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
18b20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
18b30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
18b40 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
18b50 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
18b60 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
18b70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51   the original SQ
18b80 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
18b90 2a 2a 20 7b 46 31 33 31 30 32 7d 20 49 66 20 74  ** {F13102} If t
18ba0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
18bb0 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
18bc0 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  s .**          t
18bd0 68 65 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 74  he an argument t
18be0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  o [sqlite3_sql()
18bf0 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a  ] was compiled.*
18c00 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 69  *          compi
18c10 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
18c20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18c30 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
18c40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
18c50 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  pare16()],.**   
18c60 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
18c70 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e 63  ite3_sql()] func
18c80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 4e  tion returns a N
18c90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
18ca0 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20  ** {F13103} The 
18cb0 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
18cc0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  by [sqlite3_sql(
18cd0 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74  S)] is valid unt
18ce0 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  il the.**       
18cf0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
18d00 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c  tement] S is del
18d10 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  eted using [sqli
18d20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
18d30 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
18d40 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
18d50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
18d60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18d70 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c 6c 79  EF:  Dynamically
18d80 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
18d90 65 63 74 20 20 7b 46 31 35 30 30 30 7d 0a 2a 2a  ect  {F15000}.**
18da0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
18db0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
18dc0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
18dd0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
18de0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 6f 72 20  .** that are or 
18df0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
18e00 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
18e10 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  e..** SQLite use
18e20 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
18e30 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
18e40 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20  it stores.  .** 
18e50 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
18e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
18e70 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a 2a 2a  bjects can be.**
18e80 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
18e90 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
18ea0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
18eb0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2f  OBs, or NULL..*/
18ec0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
18ed0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
18ee0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
18ef0 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69 6f  EF:  SQL Functio
18f00 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
18f10 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20   {F16001}.**.** 
18f20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
18f30 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
18f40 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
18f50 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
18f60 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
18f70 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e   object.  A poin
18f80 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
18f90 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62 6a  3_context.** obj
18fa0 65 63 74 20 69 73 20 61 6c 77 61 79 73 20 66 69  ect is always fi
18fb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
18fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
18fd0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
18fe0 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ns..*/.typedef s
18ff0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
19000 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
19010 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
19020 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67  PI3REF:  Binding
19030 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
19040 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
19050 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e  F13500}.**.** In
19060 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
19070 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
19080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19090 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72 69   and its.** vari
190a0 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20 6d  ants, literals m
190b0 61 79 20 62 65 20 72 65 70 6c 61 63 65 20 62 79  ay be replace by
190c0 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20   a parameter in 
190d0 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  one.** of these 
190e0 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  forms:.**.** <ul
190f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
19100 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
19110 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
19120 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
19130 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
19140 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d  .** In the param
19150 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e  eter forms shown
19160 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e   above NNN is an
19170 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
19180 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d 6e  ,.** VVV alpha-n
19190 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72  umeric parameter
191a0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76 61   name..** The va
191b0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61  lues of these pa
191c0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
191d0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
191e0 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a 20  meter names".** 
191f0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
19200 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
19210 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
19220 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
19230 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
19240 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ere..**.** The f
19250 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
19260 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
19270 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
19280 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f  lways.** is a po
19290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
192a0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
192b0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
192c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
192d0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
192e0 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68 65 20  s variants. The 
192f0 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
19300 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
19310 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
19320 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68 65 0a   to be set. The.
19330 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ** first paramet
19340 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
19350 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
19360 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61  same named.** pa
19370 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
19380 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
19390 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
193a0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
193b0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
193c0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
193d0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
193e0 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  . .** The index 
193f0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
19400 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
19410 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
19420 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
19430 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
19440 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
19450 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
19460 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
19470 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
19480 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
19490 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
194a0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
194b0 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
194c0 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
194d0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
194e0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
194f0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
19500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
19510 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
19520 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
19530 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
19540 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  ..**.** In those
19550 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
19560 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
19570 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
19580 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65  lue is the numbe
19590 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e  r of bytes.** in
195a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
195b0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
195c0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e  e value is the n
195d0 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
195e0 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65 20  s</u>.** in the 
195f0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
19600 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
19610 65 72 73 2e 20 20 20 54 68 65 20 6e 75 6d 62 65  ers.   The numbe
19620 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 64 6f  r.** of bytes do
19630 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
19640 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
19650 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20 6f 66  or at the end of
19660 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20   strings..** If 
19670 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
19680 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
19690 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
196a0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
196b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
196c0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
196d0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
196e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
196f0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
19700 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
19710 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
19720 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
19730 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
19740 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
19750 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
19760 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
19770 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
19780 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
19790 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
197a0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
197b0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
197c0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
197d0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
197e0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
197f0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
19800 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
19810 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
19820 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
19830 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
19840 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74  e freed..** If t
19850 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
19860 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
19870 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
19880 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
19890 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
198a0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
198b0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
198c0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
198d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
198e0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
198f0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
19900 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
19910 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
19920 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
19930 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
19940 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
19950 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62   zeros.  A zerob
19960 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
19970 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
19980 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
19990 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
199a0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
199b0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
199c0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
199d0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
199e0 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 2d   serve as place-
199f0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
19a00 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
19a10 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
19a20 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ten using .** [s
19a30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
19a40 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f   | increment BLO
19a50 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
19a60 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76   A negative.** v
19a70 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
19a80 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
19a90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
19aa0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  LOB..**.** The s
19ab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
19ac0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
19ad0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a   called after.**
19ae0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19af0 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73  e_v2()] (and its
19b00 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73   variants) or [s
19b10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
19b20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73  and.** before [s
19b30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
19b40 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20  ** Bindings are 
19b50 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
19b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
19b70 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
19b80 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74   Unbound paramet
19b90 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
19ba0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
19bb0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19bc0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
19bd0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
19be0 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  or an error code
19bf0 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20   if.** anything 
19c00 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51  goes wrong.  [SQ
19c10 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
19c20 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
19c30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
19c40 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
19c50 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  e.  [SQLITE_NOME
19c60 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
19c70 66 20 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a  f malloc fails..
19c80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
19c90 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
19ca0 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
19cb0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
19cc0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
19cd0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
19ce0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
19cf0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
19d00 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
19d10 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
19d20 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
19d30 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
19d40 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
19d50 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
19d60 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
19d70 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
19d80 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
19d90 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
19da0 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
19db0 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
19dc0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
19dd0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
19de0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
19df0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
19e00 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
19e10 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
19e20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
19e30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
19e40 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
19e50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
19e60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
19e70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
19e80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
19e90 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
19ea0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  NTS:.**.** {F135
19eb0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
19ec0 5f 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73  _prepare | SQL s
19ed0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
19ee0 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a 2a  r] recognizes.**
19ef0 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 73            tokens
19f00 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 22 3f   of the forms "?
19f10 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56  ", "?NNN", "$VVV
19f20 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22  ", ":VVV", and "
19f30 40 56 56 56 22 0a 2a 2a 20 20 20 20 20 20 20 20  @VVV".**        
19f40 20 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74    as SQL paramet
19f50 65 72 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20 69  ers, where NNN i
19f60 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f  s any sequence o
19f70 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  f one or more.**
19f80 20 20 20 20 20 20 20 20 20 20 64 69 67 69 74 73            digits
19f90 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69   and where VVV i
19fa0 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f  s any sequence o
19fb0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a 2a  f one or more .*
19fc0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 70 68 61  *          alpha
19fd0 6e 75 6d 65 72 69 63 20 63 68 61 72 61 63 74 65  numeric characte
19fe0 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
19ff0 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
1a000 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1a010 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
1a020 67 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20  g no spaces and 
1a030 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
1a040 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
1a050 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68 65  .** {F13509} The
1a060 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
1a070 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
1a080 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
1a090 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20 69  * {F13512} The i
1a0a0 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
1a0b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
1a0c0 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
1a0d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1a0e0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
1a0f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1a100 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
1a110 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
1a120 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
1a130 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
1a140 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
1a150 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
1a160 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
1a170 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1a180 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
1a190 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54 68  *.** {F13518} Th
1a1a0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
1a1b0 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
1a1c0 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
1a1d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
1a1e0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
1a1f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
1a200 66 74 6d 6f 73 74 20 6f 63 63 75 72 61 6e 63 65  ftmost occurance
1a210 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
1a220 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
1a230 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65  ter, or one more
1a240 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73   than the larges
1a250 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c  t index over all
1a260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
1a270 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c  ameters to the l
1a280 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20 74  eft if this is t
1a290 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 61  he first occurra
1a2a0 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nce.**          
1a2b0 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  of this paramete
1a2c0 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73 20  r, or 1 if this 
1a2d0 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20  is the leftmost 
1a2e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1a2f0 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20 5b 73   {F13521} The [s
1a300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1a310 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
1a320 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 20 77 69  ompiler] fail wi
1a330 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
1a340 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d  n [SQLITE_RANGE]
1a350 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
1a360 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
1a370 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
1a380 20 20 20 20 69 73 20 6c 65 73 73 20 74 68 61 6e      is less than
1a390 20 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68   1 or greater th
1a3a0 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  an SQLITE_MAX_VA
1a3b0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 2e 0a 2a  RIABLE_NUMBER..*
1a3c0 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43 61  *.** {F13524} Ca
1a3d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1a3e0 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
1a3f0 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e  te3_bind(S,N,V,.
1a400 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1a410 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76   associate the v
1a420 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20  alue V with all 
1a430 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68  SQL parameters h
1a440 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20  aving an.**     
1a450 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20       index of N 
1a460 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
1a470 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
1a480 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43 61  *.** {F13527} Ca
1a490 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1a4a0 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
1a4b0 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e  te3_bind(S,N,...
1a4c0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1a4d0 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61  verride prior ca
1a4e0 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  lls with the sam
1a4f0 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e  e values of S an
1a500 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  d N..**.** {F135
1a510 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74  30} Bindings est
1a520 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c  ablished by [sql
1a530 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1a540 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
1a550 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1a560 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73    persist across
1a570 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1a580 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a  e3_reset(S)]..**
1a590 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e 20  .** {F13533} In 
1a5a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1a5b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
1a5c0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
1a5d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1a5e0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
1a5f0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
1a600 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1a610 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1a620 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
1a630 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a  s the first L.**
1a640 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20            bytes 
1a650 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73  of the blob or s
1a660 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
1a670 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a   by V, when L.**
1a680 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
1a690 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
1a6a0 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61 6c   {F13536} In cal
1a6b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1a6c0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
1a6d0 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,D)] or.**      
1a6e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1a6f0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
1a700 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
1a710 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20  s characters.** 
1a720 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20           from V 
1a730 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
1a740 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
1a750 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74   when L is negat
1a760 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  ive..**.** {F135
1a770 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  39} In calls to 
1a780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1a790 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
1a7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a7b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
1a7c0 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
1a7d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a7e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1a7f0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
1a800 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61   D is the specia
1a810 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  l.**          co
1a820 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
1a830 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61  TATIC], SQLite a
1a840 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
1a850 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20  value V.**      
1a860 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73      is held in s
1a870 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20  tatic unmanaged 
1a880 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20  space that will 
1a890 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20  not change.**   
1a8a0 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68         during th
1a8b0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
1a8c0 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e binding..**.**
1a8d0 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61 6c   {F13542} In cal
1a8e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
1a8f0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
1a900 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
1a910 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
1a920 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
1a930 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
1a940 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
1a950 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
1a960 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
1a970 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
1a980 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
1a990 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1a9a0 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b   the routine mak
1a9b0 65 73 20 61 20 0a 2a 2a 20 20 20 20 20 20 20 20  es a .**        
1a9c0 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f    private copy o
1a9d0 66 20 56 20 76 61 6c 75 65 20 62 65 66 6f 72 65  f V value before
1a9e0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
1a9f0 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63  ** {F13545} In c
1aa00 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1aa10 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
1aa20 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
1aa30 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
1aa40 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
1aa50 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
1aa60 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
1aa70 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
1aa80 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20  D)] when D is a 
1aa90 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
1aaa0 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f         a functio
1aab0 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  n, SQLite invoke
1aac0 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  s that function 
1aad0 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  to destroy the.*
1aae0 2a 20 20 20 20 20 20 20 20 20 20 56 20 76 61 6c  *          V val
1aaf0 75 65 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ue after it has 
1ab00 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
1ab10 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  he V value..**.*
1ab20 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61  * {F13548} In ca
1ab30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1ab40 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c  bind_zeroblob(S,
1ab50 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75  N,V,L)] the valu
1ab60 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20  e bound.**      
1ab70 20 20 20 20 69 73 20 61 20 62 6c 6f 62 20 6f 66      is a blob of
1ab80 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a   L bytes, or a z
1ab90 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20  ero-length blob 
1aba0 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  if L is negative
1abb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1abc0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
1abd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1abe0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
1abf0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1ac00 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1ac10 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
1ac20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1ac30 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
1ac40 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
1ac50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ac60 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
1ac70 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
1ac80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ac90 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
1aca0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1acb0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
1acc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
1acd0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1ace0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
1acf0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
1ad00 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
1ad10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1ad20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1ad30 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
1ad40 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
1ad50 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
1ad60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1ad70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
1ad80 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
1ad90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
1ada0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
1adb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
1adc0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
1add0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
1ade0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
1adf0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
1ae00 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 46  QL Parameters {F
1ae10 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  13600}.**.** Thi
1ae20 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
1ae30 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
1ae40 65 20 6e 75 6d 62 65 72 20 6f 66 20 53 51 4c 20  e number of SQL 
1ae50 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e  parameters.** in
1ae60 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
1ae70 65 6d 65 6e 74 2e 20 20 53 51 4c 20 70 61 72 61  ement.  SQL para
1ae80 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
1ae90 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
1aea0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
1aeb0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
1aec0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
1aed0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 2d 68  ve as.** place-h
1aee0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
1aef0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
1af00 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
1af10 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
1af20 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
1af30 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
1af40 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1af50 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
1af60 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1af70 65 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d 65  e largest parame
1af80 74 65 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ter..** For all 
1af90 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
1afa0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
1afb0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6e  respond to the n
1afc0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69 71  umber of.** uniq
1afd0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
1afe0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
1aff0 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73   the ?NNN are us
1b000 65 64 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a 2a  ed, there may.**
1b010 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
1b020 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  list..**.** See 
1b030 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1b040 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1b050 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1b060 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b070 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
1b080 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1b090 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1b0a0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
1b0b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1b0c0 46 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c  F13601} The [sql
1b0d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1b0e0 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e  ter_count(S)] in
1b0f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
1b100 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1b110 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
1b120 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
1b130 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ers in the.**   
1b140 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1b150 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f   statement] S, o
1b160 72 20 30 20 69 66 20 53 0a 2a 2a 20 20 20 20 20  r 0 if S.**     
1b170 20 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f       contains no
1b180 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e   SQL parameters.
1b190 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b1a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1b1b0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
1b1c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1b1d0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
1b1e0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b  Host Parameter {
1b1f0 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13620}.**.** Th
1b200 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1b210 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1b220 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1b230 6e 2d 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72 61  n-th.** SQL para
1b240 6d 65 74 65 72 20 69 6e 20 61 20 5b 70 72 65 70  meter in a [prep
1b250 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1b260 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1b270 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
1b280 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1b290 6f 72 20 22 24 41 41 41 22 20 68 61 76 65 20 61  or "$AAA" have a
1b2a0 20 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69   name.** which i
1b2b0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41  s the string ":A
1b2c0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1b2d0 20 22 24 56 56 56 22 2e 20 0a 2a 2a 20 49 6e 20   "$VVV". .** In 
1b2e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
1b2f0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
1b300 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73  "$" or "@".** is
1b310 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
1b320 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
1b330 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
1b340 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20  the form "?" or 
1b350 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e  "?NNN" have no n
1b360 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ame..**.** The f
1b370 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
1b380 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1b390 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
1b3a0 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
1b3b0 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
1b3c0 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
1b3d0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1b3e0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
1b3f0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1b400 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
1b410 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
1b420 77 61 79 73 20 69 6e 20 74 68 65 20 55 54 46 2d  ways in the UTF-
1b430 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
1b440 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
1b450 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
1b460 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
1b470 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
1b480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b490 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
1b4a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b4b0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
1b4c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1b4d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1b4e0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1b4f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b500 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
1b510 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1b520 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1b530 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
1b540 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1b550 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71  {F13621} The [sq
1b560 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1b570 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  eter_name(S,N)] 
1b580 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1b590 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
1b5a0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
1b5b0 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  of the name of t
1b5c0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1b5d0 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
1b5e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1b5f0 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e  ent] S having in
1b600 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20  dex N, or.**    
1b610 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68        NULL if th
1b620 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61  ere is no SQL pa
1b630 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
1b640 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a  ex N or if the.*
1b650 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
1b660 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20  eter with index 
1b670 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75  N is an anonymou
1b680 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 20  s parameter "?" 
1b690 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
1b6a0 20 6e 75 6d 62 65 72 65 64 20 70 61 72 61 6d 65   numbered parame
1b6b0 74 65 72 20 22 3f 4e 4e 4e 22 2e 0a 2a 2f 0a 63  ter "?NNN"..*/.c
1b6c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1b6d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b6e0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
1b6f0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
1b700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
1b710 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
1b720 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
1b730 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a  ame {F13640}.**.
1b740 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
1b750 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
1b760 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
1b770 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
1b780 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
1b790 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
1b7a0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
1b7b0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
1b7c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1b7d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1b7e0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
1b7f0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
1b800 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
1b810 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
1b820 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
1b830 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1b840 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1b850 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1b860 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1b870 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1b880 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1b890 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1b8a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1b8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1b8c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1b8d0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1b8e0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1b8f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b900 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1b910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1b920 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1b930 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
1b940 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1b950 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
1b960 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1b970 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
1b980 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
1b990 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1b9a0 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
1b9b0 61 6d 65 74 65 72 20 69 6e 20 5b 70 72 65 70 61  ameter in [prepa
1b9c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
1b9d0 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f  *          S who
1b9e0 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20  se name matches 
1b9f0 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
1ba00 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72   N, or 0 if ther
1ba10 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
1ba20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e   no match..*/.in
1ba30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1ba40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
1ba50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
1ba60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
1ba70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ba80 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
1ba90 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
1baa0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  red Statement {F
1bab0 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e  13660}.**.** Con
1bac0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
1bad0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
1bae0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1baf0 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65  ] does not.** re
1bb00 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  set the [sqlite3
1bb10 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
1bb20 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20  dings] on a .** 
1bb30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1bb40 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73 20  ent].  Use this 
1bb50 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65  routine to.** re
1bb60 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
1bb70 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
1bb80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1bb90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31  S:.**.** {F13661
1bba0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
1bbb0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29  lear_bindings(S)
1bbc0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
1bbd0 74 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  ts all.**       
1bbe0 20 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72     SQL parameter
1bbf0 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72   bindings in [pr
1bc00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1bc10 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] S.**          
1bc20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
1bc30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
1bc40 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
1bc50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1bc60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1bc70 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
1bc80 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
1bc90 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13710}.**.** Re
1bca0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
1bcb0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
1bcc0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
1bcd0 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  urned by the .**
1bce0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1bcf0 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
1bd00 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a  ine returns 0.**
1bd10 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
1bd20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
1bd30 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
1bd40 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a  rn data (for .**
1bd50 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41   example an UPDA
1bd60 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  TE)..**.** INVAR
1bd70 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1bd80 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3711} The [sqlit
1bd90 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
1bda0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
1bdb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1bdc0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1bdd0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
1bde0 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61  esult set genera
1bdf0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ted by the.**   
1be00 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1be10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f   statement] S, o
1be20 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f  r 0 if S does no
1be30 74 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20  t generate.**   
1be40 20 20 20 20 20 20 20 61 20 72 65 73 75 6c 74 20         a result 
1be50 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1be60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
1be70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1be80 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1be90 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
1bea0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
1beb0 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a   Set {F13720}.**
1bec0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1bed0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
1bee0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
1bef0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
1bf00 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
1bf10 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
1bf20 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
1bf30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
1bf40 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
1bf50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
1bf60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
1bf70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1bf80 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  F8 string.** and
1bf90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1bfa0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
1bfb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1bfc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1bfd0 2a 2a 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  ** UTF16 string.
1bfe0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1bff0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1c000 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1c010 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d  ent] that implem
1c020 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54 20  ents the SELECT 
1c030 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1c040 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c050 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e  er is the column
1c060 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
1c070 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
1c080 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  s.** number 0..*
1c090 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  *.** The returne
1c0a0 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
1c0b0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1c0c0 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b  either the .** [
1c0d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c0e0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
1c0f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
1c100 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
1c110 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
1c120 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
1c130 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
1c140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1c150 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
1c160 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
1c170 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
1c180 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
1c190 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
1c1a0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
1c1b0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
1c1c0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
1c1d0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
1c1e0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
1c1f0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1c200 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
1c210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
1c220 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
1c230 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
1c240 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
1c250 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
1c260 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
1c270 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
1c280 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
1c290 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
1c2a0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
1c2b0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
1c2c0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
1c2d0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
1c2e0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
1c2f0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
1c300 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
1c310 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
1c320 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  21} A successful
1c330 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
1c340 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
1c350 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a  mn_name(S,N)].**
1c360 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1c370 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1c380 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
1c390 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
1c3a0 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 20 74  mn (where 0 is t
1c3b0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
1c3c0 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20  umn) for the.** 
1c3d0 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
1c3e0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
1c3f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
1c400 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a   a.**          z
1c410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1c420 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1c430 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41 20 73 75  ** {F13723} A su
1c440 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1c450 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
1c460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1c470 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
1c480 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
1c490 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a  turns the name.*
1c4a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1c4b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
1c4c0 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65 66  ere 0 is the lef
1c4d0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  t-most column) f
1c4e0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
1c4f0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
1c500 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1c510 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20  ment] S as a.** 
1c520 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1c530 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
1c540 73 74 72 69 6e 67 20 69 6e 20 74 68 65 20 6e 61  string in the na
1c550 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1c560 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20  .**.** {F13724} 
1c570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
1c580 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
1c590 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c5a0 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20  name16()].**    
1c5b0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1c5c0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
1c5d0 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61  ointer if they a
1c5e0 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20  re unable to.** 
1c5f0 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
1c600 65 20 6d 65 6d 6f 72 79 20 6d 65 6d 6f 72 79 20  e memory memory 
1c610 74 6f 20 68 6f 6c 64 20 74 68 65 72 65 20 6e 6f  to hold there no
1c620 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69  rmal return stri
1c630 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ngs..**.** {F137
1c640 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72  25} If the N par
1c650 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1c660 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
1c670 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
1c680 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
1c690 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
1c6a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1c6b0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
1c6c0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1c6d0 73 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  s returns a NULL
1c6e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 0a 2a 2a   pointer..** .**
1c6f0 20 7b 46 31 33 37 32 36 7d 20 54 68 65 20 73 74   {F13726} The st
1c700 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1c710 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1c720 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64  n_name(S,N)] and
1c730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1c740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1c750 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61  e16(S,N)] are va
1c760 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  lid until the ne
1c770 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  xt.**          c
1c780 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f  all to either ro
1c790 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73  utine with the s
1c7a0 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61  ame S and N para
1c7b0 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  meters.**       
1c7c0 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c     or until [sql
1c7d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
1c7e0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a  ] is called..**.
1c7f0 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e  ** {F13727} When
1c800 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1c810 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
1c820 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e  tatement contain
1c830 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
1c840 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20   AS clause, the 
1c850 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c  name of that col
1c860 75 6d 6e 20 69 73 20 74 68 65 20 69 6e 64 65 6e  umn is the inden
1c870 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20  tifier.**       
1c880 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20     to the right 
1c890 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  of the AS keywor
1c8a0 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
1c8b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1c8c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1c8d0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
1c8e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1c8f0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
1c900 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1c910 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
1c920 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
1c930 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
1c940 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34 30 7d   Result {F13740}
1c950 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1c960 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
1c970 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
1c980 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
1c990 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
1c9a0 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
1c9b0 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
1c9c0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1c9d0 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
1c9e0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
1c9f0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
1ca00 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
1ca10 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
1ca20 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 38 20  * either a UTF8 
1ca30 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e 67 2e  or UTF16 string.
1ca40 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
1ca50 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1ca60 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1ca70 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
1ca80 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
1ca90 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
1caa0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
1cab0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
1cac0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
1cad0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
1cae0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1caf0 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20   valid until.** 
1cb00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1cb10 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1cb20 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  royed using.** [
1cb30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1cb40 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1cb50 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1cb60 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
1cb70 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
1cb80 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
1cb90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
1cba0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
1cbb0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
1cbc0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
1cbd0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
1cbe0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
1cbf0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
1cc00 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1cc10 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
1cc20 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
1cc30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1cc40 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1cc50 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1cc60 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
1cc70 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1cc80 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73 74 61  d by .** the sta
1cc90 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
1cca0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
1ccb0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
1ccc0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
1ccd0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1cce0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
1ccf0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
1cd00 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65  ion.** or subque
1cd10 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
1cd20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
1cd30 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
1cd40 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
1cd50 75 72 6e 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  urn NULL.  These
1cd60 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
1cd70 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
1cd80 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
1cd90 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
1cda0 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
1cdb0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
1cdc0 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  the .** name of 
1cdd0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
1cde0 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64  abase, table and
1cdf0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
1ce00 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  ry result.** col
1ce10 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
1ce20 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
1ce30 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
1ce40 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
1ce50 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
1ce60 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
1ce70 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1ce80 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
1ce90 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
1cea0 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
1ceb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
1cec0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
1ced0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
1cee0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
1cef0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
1cf00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
1cf10 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70  MN_METADATA prep
1cf20 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20  rocessor symbol 
1cf30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  defined..**.** {
1cf40 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77  U13751}.** If tw
1cf50 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
1cf60 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
1cf70 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
1cf80 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
1cf90 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
1cfa0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
1cfb0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
1cfc0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1cfd0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
1cfe0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1cff0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1d000 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20  ** {F13741} The 
1d010 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1d020 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c  database_name(S,
1d030 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1d040 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1d050 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1d060 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1d070 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ed name of the d
1d080 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69  atabase from whi
1d090 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1d0a0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1d0b0 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1d0c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1d0d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1d0e0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1d0f0 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1d100 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1d110 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1d120 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1d130 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1d140 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1d150 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1d160 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1d170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1d180 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {F13742} The [s
1d190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1d1a0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
1d1b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
1d1c0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
1d1d0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
1d1e0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
1d1f0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
1d200 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1d210 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
1d220 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
1d230 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
1d240 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
1d250 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
1d260 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
1d270 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
1d280 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
1d290 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74 68  L if the the Nth
1d2a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
1d2b0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
1d2c0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
1d2d0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
1d2e0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1d2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1d300 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
1d310 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
1d320 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {F13743} The [sq
1d330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
1d340 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
1d350 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1d360 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
1d370 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
1d380 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
1d390 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
1d3a0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a  rom which the .*
1d3b0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
1d3c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
1d3d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d3e0 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20  ent] S .**      
1d3f0 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64      is extracted
1d400 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
1d410 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1d420 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20  of S is a.**    
1d430 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78        general ex
1d440 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
1d450 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d460 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
1d470 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
1d480 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20  e name..**      
1d490 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d      .** {F13744}
1d4a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
1d4b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
1d4c0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
1d4d0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
1d4e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1d4f0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
1d500 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
1d510 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
1d520 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
1d530 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
1d540 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1d550 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1d560 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1d570 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1d580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1d590 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1d5a0 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1d5b0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1d5c0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1d5d0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1d5e0 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1d5f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1d600 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1d610 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1d620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1d630 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20 5b 73   {F13745} The [s
1d640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1d650 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  igin_name(S,N)] 
1d660 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1d670 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
1d680 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
1d690 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
1d6a0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
1d6b0 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
1d6c0 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  ch the .**      
1d6d0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
1d6e0 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72  olumn of [prepar
1d6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1d700 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1d710 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
1d720 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e 74  LL if the the Nt
1d730 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
1d740 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
1d750 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
1d760 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
1d770 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1d780 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
1d790 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
1d7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
1d7b0 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73   {F13746} The [s
1d7c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
1d7d0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  igin_name16(S,N)
1d7e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1d7f0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
1d800 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
1d810 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
1d820 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
1d830 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1d840 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
1d850 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
1d860 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
1d870 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
1d880 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
1d890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1d8a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
1d8b0 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
1d8c0 55 4c 4c 20 69 66 20 74 68 65 20 74 68 65 20 4e  ULL if the the N
1d8d0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
1d8e0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
1d8f0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
1d900 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
1d910 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1d920 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
1d930 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
1d940 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a  ..**          .*
1d950 2a 20 7b 46 31 33 37 34 38 7d 20 54 68 65 20 72  * {F13748} The r
1d960 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f  eturn values fro
1d970 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  m.**          [s
1d980 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
1d990 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75  tabase_name|colu
1d9a0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
1d9b0 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
1d9c0 20 20 20 20 61 72 65 20 76 61 6c 69 64 0a 2a 2a      are valid.**
1d9d0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
1d9e0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
1d9f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1da00 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
1da10 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20     or until the 
1da20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e  encoding is chan
1da30 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d  ged by another m
1da40 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
1da50 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
1da60 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ll for the same 
1da70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1da80 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  nt and column..*
1da90 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
1daa0 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d  :.**.** {U13751}
1dab0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
1dac0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
1dad0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20   or more.**     
1dae0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
1daf0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1db00 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61  me|column metada
1db10 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
1db20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
1db30 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
1db40 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
1db50 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
1db60 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
1db70 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
1db80 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
1db90 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
1dba0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1dbb0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
1dbc0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1dbd0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1dbe0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1dbf0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
1dc00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
1dc10 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
1dc20 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
1dc30 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
1dc40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1dc50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1dc60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
1dc70 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
1dc80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
1dc90 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1dca0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
1dcb0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1dcc0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
1dcd0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
1dce0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
1dcf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1dd00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1dd10 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
1dd20 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
1dd30 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36  ry Result {F1376
1dd40 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0}.**.** The fir
1dd50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1dd60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1dd70 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20 74  ement]. .** If t
1dd80 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
1dd90 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
1dda0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
1ddb0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a 2a  column of the .*
1ddc0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
1ddd0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 53 45  t set of that SE
1dde0 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65 20  LECT is a table 
1ddf0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
1de00 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
1de10 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
1de20 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
1de30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
1de40 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
1de50 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
1de60 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
1de70 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
1de80 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
1de90 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
1dea0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
1deb0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
1dec0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1ded0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
1dee0 2d 38 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45 4e  -8 encoded.  {EN
1def0 44 7d 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  D} .** For examp
1df00 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 61 62  le, in the datab
1df10 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
1df20 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
1df30 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
1df40 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c  *.** And the fol
1df50 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
1df60 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
1df70 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
1df80 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
1df90 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * Then this rout
1dfa0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
1dfb0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
1dfc0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
1dfd0 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63  cond.** result c
1dfe0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
1dff0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
1e000 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
1e010 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
1e020 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
1e030 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
1e040 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
1e050 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
1e060 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
1e070 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
1e080 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
1e090 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
1e0a0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
1e0b0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
1e0c0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
1e0d0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
1e0e0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
1e0f0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
1e100 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
1e110 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
1e120 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
1e130 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
1e140 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
1e150 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
1e160 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
1e170 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
1e180 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
1e190 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1e1a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d  :.**.** {F13761}
1e1b0 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
1e1c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1e1d0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
1e1e0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
1e1f0 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72     returns a zer
1e200 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1e210 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
1e220 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ning the.**     
1e230 20 20 20 20 20 20 74 68 65 20 64 65 63 6c 61 72        the declar
1e240 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ed datatype of t
1e250 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1e260 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20  that appears.** 
1e270 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
1e280 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
1e290 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
1e2a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e2b0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1e2c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
1e2d0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
1e2e0 2a 20 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75  * {F13762}  A su
1e2f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1e300 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e310 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29  _decltype16(S,N)
1e320 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
1e330 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
1e340 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20  rminated UTF-16 
1e350 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1e360 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  r string.**     
1e370 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67        containing
1e380 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61   the declared da
1e390 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  tatype of the ta
1e3a0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
1e3b0 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20  appears.**      
1e3c0 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20       as the Nth 
1e3d0 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64  column (numbered
1e3e0 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
1e3f0 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
1e400 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
1e410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e420 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nt] S..**.** {F1
1e430 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c  3763}  If N is l
1e440 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20  ess than 0 or N 
1e450 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1e460 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20  or equal to.**  
1e470 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d           the num
1e480 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1e490 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
1e4a0 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
1e4b0 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65 20        or if the 
1e4c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
1e4d0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
1e4e0 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61 74   or subquery rat
1e4f0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
1e500 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f   than a table co
1e510 6c 75 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65 6d  lumn or if a mem
1e520 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1e530 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20  ailure.**       
1e540 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e      occurs durin
1e550 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65  g encoding conve
1e560 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20  rsions, then.** 
1e570 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20            calls 
1e580 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
1e590 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
1e5a0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
1e5b0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
1e5c0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
1e5d0 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a  )] return NULL..
1e5e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1e5f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1e600 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
1e610 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
1e620 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1e630 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
1e640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
1e650 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50  nt);../* .** CAP
1e660 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74 65  I3REF:  Evaluate
1e670 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1e680 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13200}.**.**
1e690 20 41 66 74 65 72 20 61 6e 20 5b 70 72 65 70 61   After an [prepa
1e6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
1e6b0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
1e6c0 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a 20   with a call.** 
1e6d0 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  to either [sqlit
1e6e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e6f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1e700 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
1e710 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  to one of.** the
1e720 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1e730 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
1e740 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
1e750 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
1e760 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66 75  .** then this fu
1e770 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 63  nction must be c
1e780 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
1e790 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
1e7a0 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61 74  ate the .** stat
1e7b0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
1e7c0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
1e7d0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
1e7e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1e7f0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
1e800 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
1e810 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
1e820 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
1e830 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
1e840 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
1e850 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e860 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e870 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
1e880 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
1e890 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
1e8a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e8b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
1e8c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
1e8d0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
1e8e0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
1e8f0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
1e900 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
1e910 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
1e920 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
1e930 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
1e940 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
1e950 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ted..**.** In th
1e960 65 20 6c 61 67 61 63 79 20 69 6e 74 65 72 66 61  e lagacy interfa
1e970 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
1e980 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
1e990 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
1e9a0 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ], .** [SQLITE_D
1e9b0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
1e9c0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
1e9d0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
1e9e0 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
1e9f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1ea00 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
1ea10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  ther [SQLITE_OK 
1ea20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a 2a  | result code].*
1ea30 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
1ea40 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
1ea50 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1ea60 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
1ea70 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a  d as.** well..**
1ea80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1ea90 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
1eaa0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
1eab0 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
1eac0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
1ead0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
1eae0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
1eaf0 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
1eb00 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d  tement is a COMM
1eb10 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  IT.** or occurs 
1eb20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
1eb30 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1eb40 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
1eb50 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
1eb60 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
1eb70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
1eb80 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f  t a COMMIT and o
1eb90 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
1eba0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
1ebb0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
1ebc0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
1ebd0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
1ebe0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
1ebf0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
1ec00 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
1ec10 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
1ec20 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
1ec30 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
1ec40 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
1ec50 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
1ec60 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
1ec70 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
1ec80 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
1ec90 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
1eca0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1ecb0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
1ecc0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
1ecd0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
1ece0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
1ecf0 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
1ed00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
1ed10 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
1ed20 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
1ed30 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  then .** [SQLITE
1ed40 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e 65  _ROW] is returne
1ed50 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
1ed60 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
1ed70 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70 72   ready.** for pr
1ed80 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 20  ocessing by the 
1ed90 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
1eda0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
1edb0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  ed using.** the 
1edc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1edd0 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63 63  int | column acc
1ede0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
1edf0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
1ee00 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
1ee10 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
1ee20 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
1ee30 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49  ta..** .** [SQLI
1ee40 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
1ee50 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
1ee60 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
1ee70 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
1ee80 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
1ee90 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
1eea0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
1eeb0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
1eec0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
1eed0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
1eee0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
1eef0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1ef00 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
1ef10 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
1ef20 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
1ef30 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
1ef40 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a  r code (example:
1ef50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
1ef60 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
1ef70 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
1ef80 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
1ef90 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
1efa0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
1efb0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1efc0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
1efd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1efe0 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
1eff0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
1f000 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
1f010 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
1f020 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
1f030 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
1f040 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
1f050 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
1f060 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
1f070 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
1f080 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
1f090 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
1f0a0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
1f0b0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
1f0c0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
1f0d0 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
1f0e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
1f0f0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
1f100 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
1f110 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f 75   had .** previou
1f120 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
1f130 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
1f140 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
1f150 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
1f160 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
1f170 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1f180 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
1f190 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
1f1a0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
1f1b0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
1f1c0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
1f1d0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
1f1e0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
1f1f0 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  /b>.** In the le
1f200 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
1f210 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
1f220 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61 79  step() API alway
1f230 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
1f240 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 0a  ric error code,.
1f250 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
1f260 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
1f270 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
1f280 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1f290 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  ** and [SQLITE_M
1f2a0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
1f2b0 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
1f2c0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
1f2d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1f2e0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
1f2f0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 20  find one of the 
1f300 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72 72  specific.** [err
1f310 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
1f320 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
1f330 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
1f340 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
1f350 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
1f360 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
1f370 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
1f380 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
1f390 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
1f3a0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
1f3b0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
1f3c0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
1f3d0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1f3e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1f3f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f400 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
1f410 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
1f420 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
1f430 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
1f440 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f450 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20 6d  , then the .** m
1f460 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
1f470 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
1f480 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
1f490 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
1f4a0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
1f4b0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
1f4c0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
1f4d0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
1f4e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1f4f0 31 33 32 30 32 7d 20 20 49 66 20 5b 70 72 65 70  13202}  If [prep
1f500 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f510 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
1f520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 75  .**           ru
1f530 6e 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  n, then [sqlite3
1f540 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63  _step(S)] advanc
1f550 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64  es that prepared
1f560 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
1f570 20 20 20 20 20 20 20 20 75 6e 74 69 6c 20 74 6f          until to
1f580 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75   completion or u
1f590 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79  ntil it is ready
1f5a0 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
1f5b0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
1f5c0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
1f5d0 74 20 73 65 74 20 6f 72 20 61 6e 20 69 6e 74 65  t set or an inte
1f5e0 72 72 75 70 74 20 6f 72 20 72 75 6e 2d 74 69 6d  rrupt or run-tim
1f5f0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
1f600 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20  **.** {F15304}  
1f610 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
1f620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
1f630 20 63 61 75 73 65 73 20 74 68 65 20 0a 2a 2a 20   causes the .** 
1f640 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1f650 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
1f660 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c   to run to compl
1f670 65 74 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20 20  etion,.**       
1f680 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e      the function
1f690 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1f6a0 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
1f6b0 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
1f6c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1f6d0 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
1f6e0 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
1f6f0 64 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  dy.**           
1f700 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65  to return anothe
1f710 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
1f720 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
1f730 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
1f740 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a   [SQLITE_ROW]..*
1f750 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20 49  *.** {F15308}  I
1f760 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
1f770 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e  ite3_step(S)] en
1f780 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20  counters an.**  
1f790 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f7a0 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74 65  3_interrupt|inte
1f7b0 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
1f7c0 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  time error,.**  
1f7d0 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75           it retu
1f7e0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 61 69  rns an approprai
1f7f0 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  te error code th
1f800 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  at is not one of
1f810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
1f820 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49  QLITE_OK], [SQLI
1f830 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c  TE_ROW], or [SQL
1f840 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
1f850 20 7b 46 31 35 33 31 30 7d 20 20 49 66 20 61 6e   {F15310}  If an
1f860 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
1f870 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f  upt|interrupt] o
1f880 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  r run-time error
1f890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
1f8a0 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61  curs during a ca
1f8b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
1f8c0 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  tep(S)].**      
1f8d0 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70       for a [prep
1f8e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f8f0 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  S created using.
1f900 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67  **           leg
1f910 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
1f920 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f930 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1f940 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1f950 61 72 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68  are16()] then th
1f960 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
1f970 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
1f980 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
1f990 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  RROR], [SQLITE_B
1f9a0 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  USY], or [SQLITE
1f9b0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74  _MISUSE]..*/.int
1f9c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
1f9d0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1f9e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1f9f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1fa00 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
1fa10 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F13770}.**.** 
1fa20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
1fa30 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
1fa40 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
1fa50 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
1fa60 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1fa70 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37  TS:.**.** {F1377
1fa80 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c  1}  After a call
1fa90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
1faa0 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72  p(S)] that retur
1fab0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ns.**           
1fac0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
1fad0 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
1fae0 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
1faf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 77  e.**           w
1fb00 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
1fb10 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65  ame value as the
1fb20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
1fb30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
1fb40 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e  unt(S)] function
1fb50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d  ..**.** {F13772}
1fb60 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33    After [sqlite3
1fb70 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65  _step(S)] has re
1fb80 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65  turned any value
1fb90 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
1fba0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1fbb0 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20  _ROW] or before 
1fbc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
1fbd0 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20 20  ] has been .**  
1fbe0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20           called 
1fbf0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
1fc00 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 0a   statement] for.
1fc10 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
1fc20 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63   first time sinc
1fc30 65 20 69 74 20 77 61 73 20 5b 73 71 6c 69 74 65  e it was [sqlite
1fc40 33 5f 70 72 65 70 61 72 65 7c 70 72 65 70 61 72  3_prepare|prepar
1fc50 65 64 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed].**          
1fc60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1fc70 65 74 7c 72 65 73 65 74 5d 2c 20 74 68 65 20 5b  et|reset], the [
1fc80 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
1fc90 6e 74 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  nt(S)].**       
1fca0 20 20 20 20 72 6f 75 74 69 6e 65 20 72 65 74 75      routine retu
1fcb0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74  rns zero..*/.int
1fcc0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
1fcd0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1fce0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1fcf0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
1fd00 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
1fd10 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59   {F10265}.** KEY
1fd20 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
1fd30 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36 36  XT.**.** {F10266
1fd40 7d 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  }Every value in 
1fd50 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
1fd60 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
1fd70 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
1fd80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1fd90 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
1fda0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
1fdb0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
1fdc0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
1fdd0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
1fde0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
1fdf0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
1fe00 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
1fe10 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
1fe20 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
1fe30 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
1fe40 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1fe50 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
1fe60 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
1fe70 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
1fe80 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
1fe90 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
1fea0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
1feb0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
1fec0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
1fed0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
1fee0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
1fef0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
1ff00 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
1ff10 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53 51  3_TEXT not.** SQ
1ff20 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
1ff30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
1ff40 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
1ff50 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
1ff60 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
1ff70 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
1ff80 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
1ff90 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
1ffa0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
1ffb0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
1ffc0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
1ffd0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
1ffe0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
1fff0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
20000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20010 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73 20   Results Values 
20020 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 46 31  From A Query {F1
20030 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  3800}.**.** Thes
20040 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
20050 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
20060 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
20070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
20080 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
20090 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 0a  formation about.
200a0 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ** a single colu
200b0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
200c0 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  t result row of 
200d0 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
200e0 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 66  ry.** case the f
200f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
20100 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
20110 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  e .** [prepared 
20120 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
20130 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
20140 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
20150 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
20160 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
20170 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
20180 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20190 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
201a0 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
201b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
201c0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
201d0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
201e0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
201f0 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
20200 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
20210 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
20220 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
20230 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
20240 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
20250 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20260 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
20270 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
20280 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
20290 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
202a0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
202b0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
202c0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
202d0 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
202e0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
202f0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
20300 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
20310 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
20320 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
20330 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
20340 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
20350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20360 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
20370 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
20380 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
20390 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
203a0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
203b0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
203c0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
203d0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
203e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
203f0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
20400 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
20410 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
20420 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
20430 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
20440 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
20450 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
20460 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20470 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
20480 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
20490 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
204a0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
204b0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
204c0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
204d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
204e0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
204f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
20500 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
20510 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
20520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
20530 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20540 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
20550 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
20560 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
20570 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
20580 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
20590 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
205a0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
205b0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
205c0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
205d0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
205e0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
205f0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
20600 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
20610 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
20620 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
20630 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
20640 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
20650 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
20660 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
20670 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
20680 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
20690 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
206a0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
206b0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
206c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
206d0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
206e0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
206f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
20700 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
20710 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
20720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
20730 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
20740 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
20750 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
20760 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
20770 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
20780 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
20790 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
207a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
207b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
207c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
207d0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
207e0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
207f0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
20800 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
20810 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
20820 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
20830 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
20840 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
20850 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
20860 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
20870 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
20880 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
20890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
208a0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
208b0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
208c0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
208d0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
208e0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
208f0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
20900 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
20910 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
20920 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
20930 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
20940 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
20950 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
20960 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
20970 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
20980 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
20990 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
209a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
209b0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
209c0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
209d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
209e0 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
209f0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
20a00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
20a10 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
20a20 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
20a30 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
20a40 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
20a50 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
20a60 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
20a70 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
20a80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
20a90 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
20aa0 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62 69   blob is an arbi
20ab0 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
20ac0 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
20ad0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
20ae0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20af0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
20b00 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
20b10 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
20b20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
20b30 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
20b40 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
20b50 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
20b60 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
20b70 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20 54  of UTF-8.  .** T
20b80 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
20b90 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
20ba0 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
20bb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
20bc0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
20bd0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
20be0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
20bf0 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
20c00 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
20c10 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
20c20 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
20c30 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
20c40 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
20c50 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
20c60 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
20c70 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f  internally to do
20c80 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a   the conversion.
20c90 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
20ca0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
20cb0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
20cc0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74  he conversions t
20cd0 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69  hat.** are appli
20ce0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
20cf0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
20d00 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
20d10 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
20d20 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
20d30 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
20d40 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
20d50 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
20d60 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
20d70 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
20d80 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
20d90 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
20da0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
20db0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
20dc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20dd0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
20de0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
20df0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
20e00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
20e10 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
20e20 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
20e30 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
20e40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
20e50 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
20e60 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
20e70 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
20e80 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
20e90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
20ea0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
20eb0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
20ec0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
20ed0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
20ee0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
20ef0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
20f00 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45   for INTEGER->TE
20f10 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
20f20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
20f30 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
20f40 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
20f50 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
20f60 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
20f70 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
20f80 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
20f90 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
20fa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
20fb0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
20fc0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
20fd0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
20fe0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
20ff0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
21000 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
21010 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
21020 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
21030 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
21040 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
21050 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
21060 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
21070 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
21080 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
21090 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
210a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
210b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
210c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
210d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
210e0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
210f0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
21100 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
21110 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
21120 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
21130 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
21140 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
21150 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
21160 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
21170 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
21180 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
21190 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
211a0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
211b0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
211c0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
211d0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
211e0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
211f0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
21200 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61 76   its.** on equav
21210 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
21220 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
21230 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
21240 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
21250 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
21260 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
21270 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
21280 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
21290 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
212a0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
212b0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
212c0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
212d0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
212e0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
212f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
21300 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
21310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
21320 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
21330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21340 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
21350 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54  validated. .** T
21360 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
21370 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
21380 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
21390 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
213a0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
213b0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
213c0 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
213d0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
213e0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
213f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
21400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
21410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
21420 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
21430 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
21440 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
21450 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20          need to 
21460 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
21470 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e  string.</p></li>
21480 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  .**.** <li><p>  
21490 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
214a0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
214b0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
214c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
214d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71  r.**          sq
214e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
214f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
21500 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
21510 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
21520 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 55  **          to U
21530 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  TF-16.</p></li>.
21540 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54  **.** <li><p>  T
21550 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
21560 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
21570 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
21580 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
21590 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69  **          sqli
215a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
215b0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
215c0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
215d0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
215e0 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38          to UTF-8
215f0 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  .</p></li>.** </
21600 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72  ul>.**.** Conver
21610 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
21620 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
21630 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
21640 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
21650 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
21660 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
21670 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
21680 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
21690 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
216a0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
216b0 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e  ior pointer poin
216c0 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20  ts to will have 
216d0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
216e0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
216f0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
21700 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
21710 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
21720 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
21730 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f   it is.** not po
21740 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
21750 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
21760 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
21770 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a  alidated.  .**.*
21780 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
21790 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
217a0 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
217b0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
217c0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
217d0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
217e0 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20  ng ways:.**.**  
217f0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
21800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21810 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
21820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21830 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
21840 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
21850 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
21860 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
21870 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
21880 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
21890 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
218a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
218b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
218c0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  s16()</li>.**  <
218d0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
218e0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
218f0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
21900 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
21910 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
21920 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73  _blob(),.** or s
21930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
21940 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
21950 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
21960 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
21970 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65  d.** format, the
21980 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
21990 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
219a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
219b0 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a 2a  n_bytes16() to.*
219c0 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  * find the size 
219d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
219e0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20  Do not mix call 
219f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21a00 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73  n_text() or.** s
21a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
21a20 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
21a30 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21a40 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41 6e  n_bytes16().  An
21a50 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20  d do not.** mix 
21a60 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
21a70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
21a80 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
21a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
21aa0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tes()..**.** The
21ab0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
21ac0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
21ad0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
21ae0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
21af0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
21b00 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
21b10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
21b20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21b30 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
21b40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
21b50 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d  called.  The mem
21b60 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
21b70 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
21b80 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66  * and blobs is f
21b90 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
21ba0 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
21bb0 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
21bc0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
21bd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21be0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
21bf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
21c00 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a  ], etc. into .**
21c10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
21c20 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
21c30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21c40 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
21c50 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
21c60 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
21c70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
21c80 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
21c90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
21ca0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
21cb0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
21cc0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
21cd0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
21ce0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
21cf0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
21d00 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
21d10 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
21d20 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
21d30 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
21d40 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
21d50 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21d60 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20 5b 73   {F13803} The [s
21d70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
21d80 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(S,N)] interfa
21d90 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
21da0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
21db0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
21dc0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
21dd0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
21de0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
21df0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21e00 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61   S into a blob a
21e10 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
21e20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
21e30 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
21e40 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
21e50 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54 68 65  .** {F13806} The
21e60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21e70 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74  _bytes(S,N)] int
21e80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21e90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
21ea0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
21eb0 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74  n the blob or st
21ec0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
21ed0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
21ee0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
21ef0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
21f00 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
21f10 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
21f20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
21f30 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
21f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
21f50 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
21f60 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
21f70 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e  lumn_text(S,N)].
21f80 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39 7d 20  .**.** {F13809} 
21f90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
21fa0 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29  umn_bytes16(S,N)
21fb0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21fc0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
21fd0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
21fe0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
21ff0 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
22000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22010 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
22020 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
22030 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
22040 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
22050 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
22060 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22070 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
22080 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ,N)]..**.** {F13
22090 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  812} The [sqlite
220a0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
220b0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
220c0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
220d0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
220e0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
220f0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
22100 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
22110 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22120 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
22130 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
22140 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
22150 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
22160 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
22170 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
22180 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71  {F13815} The [sq
22190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
221a0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
221b0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
221c0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
221d0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
221e0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
221f0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
22200 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
22210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
22220 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
22230 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
22240 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
22250 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
22260 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
22270 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
22280 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c  F13818} The [sql
22290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
222a0 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  4(S,N)] interfac
222b0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
222c0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
222d0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
222e0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
222f0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
22300 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
22310 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22320 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
22330 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
22340 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
22350 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
22360 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
22370 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20 54 68  *.** {F13821} Th
22380 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22390 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74  n_text(S,N)] int
223a0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
223b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
223c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
223d0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
223e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
223f0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
22400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22410 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
22420 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
22430 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-8 .**         
22440 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
22450 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
22460 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
22470 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54 68 65  .** {F13824} The
22480 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22490 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e  _text16(S,N)] in
224a0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
224b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
224c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
224d0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
224e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
224f0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
22500 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22510 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a  ment] S into a z
22520 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
22530 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
22540 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
22550 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
22560 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
22570 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
22580 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
22590 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
225a0 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65 20 5b  * {F13827} The [
225b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
225c0 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ype(S,N)] interf
225d0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
225e0 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b          one of [
225f0 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53  SQLITE_NULL], [S
22600 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
22610 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a  [SQLITE_FLOAT],.
22620 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
22630 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53  ITE_TEXT], or [S
22640 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
22650 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a  ppropriate for.*
22660 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 4e  *          the N
22670 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
22680 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
22690 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
226a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
226b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
226c0 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nt] S..**.** {F1
226d0 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  3830} The [sqlit
226e0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
226f0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22700 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
22710 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
22720 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
22730 6c 75 65 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  lue] object that
22740 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
22750 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
22760 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
22770 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
22780 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
22790 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
227a0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
227b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
227c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
227d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
227e0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
227f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22800 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
22810 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
22820 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22830 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
22840 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
22850 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
22860 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
22870 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22880 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
22890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
228a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
228b0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
228c0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
228d0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
228e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
228f0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
22900 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
22910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22930 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
22940 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
22950 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
22960 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
22970 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
22980 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
22990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
229a0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
229b0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
229c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
229d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
229e0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
229f0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
22a00 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
22a10 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33  ent Object {F133
22a20 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
22a30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22a40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
22a50 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
22a60 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
22a70 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65  atement]. If the
22a80 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
22a90 2a 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  * executed succe
22aa0 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20  ssfully, or not 
22ab0 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
22ac0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20   then SQLITE_OK 
22ad0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
22ae0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
22af0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
22b00 69 6c 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a  iled then an .**
22b10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
22b20 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
22b30 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74   code].** is ret
22b40 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68  urned. .**.** Th
22b50 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
22b60 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
22b70 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
22b80 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
22b90 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
22ba0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74  tatement].  If t
22bb0 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69  he virtual machi
22bc0 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63  ne has not .** c
22bd0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
22be0 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
22bf0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
22c00 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
22c10 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
22c20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65  error or an inte
22c30 72 72 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71  rrupt.  (See [sq
22c40 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
22c50 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c  )].) .** Incompl
22c60 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20  ete updates may 
22c70 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
22c80 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  nd transactions 
22c90 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a 2a 2a 20  cancelled,  .** 
22ca0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
22cb0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
22cc0 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72  and the .** [err
22cd0 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
22ce0 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
22cf0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
22d00 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
22d10 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b  * {F11302} The [
22d20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22d30 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
22d40 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20  estroys the.**  
22d50 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
22d60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
22d70 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a  nd releases all.
22d80 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
22d90 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f  ry and file reso
22da0 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68  urces held by th
22db0 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  at object..**.**
22dc0 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68 65   {F11304} If the
22dd0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
22de0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
22df0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
22e00 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
22e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22e20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72  S returned an er
22e30 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
22e40 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   then [sqlite3_f
22e50 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75  inalize(S)] retu
22e60 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72  rns that same er
22e70 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ror..*/.int sqli
22e80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
22e90 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
22ea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22eb0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
22ec0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
22ed0 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a  bject {F13330}.*
22ee0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22ef0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
22f00 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
22f10 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70  eset a .** [prep
22f20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22f30 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20  object..** back 
22f40 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
22f50 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
22f60 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
22f70 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d  * Any SQL statem
22f80 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
22f90 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
22fa0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
22fb0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
22fc0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
22fd0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
22fe0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
22ff0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
23000 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
23010 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
23020 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
23030 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d  ..**.** {F11332}
23040 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
23050 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
23060 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
23070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23080 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] S.**          
23090 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
230a0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
230b0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  gram..**.** {F11
230c0 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  334} If the most
230d0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
230e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
230f0 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20  ] for .**       
23100 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
23110 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
23120 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
23130 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
23140 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
23150 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
23160 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
23170 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
23180 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20  ed on S,.**     
23190 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
231a0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
231b0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
231c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d  ..**.** {F11336}
231d0 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
231e0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
231f0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
23200 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
23210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23220 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
23230 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
23240 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
23250 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
23260 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
23270 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
23280 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d  ..**.** {F11338}
23290 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
232a0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
232b0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
232c0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
232d0 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20           of any 
232e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
232f0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
23300 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23310 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
23320 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
23330 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
23340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23350 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
23360 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
23370 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a  ions {F16100}.**
23380 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
23390 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
233a0 75 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54  utines} .**.** T
233b0 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f  hese two functio
233c0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
233d0 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75   known as.** "fu
233e0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
233f0 72 6f 75 74 69 6e 65 73 22 29 20 61 72 65 20 75  routines") are u
23400 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
23410 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
23420 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20  egates.** or to 
23430 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
23440 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74 69 6e  avior of existin
23450 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
23460 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
23470 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63  The.** differenc
23480 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e 20 74  e only between t
23490 68 65 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  he two is that t
234a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
234b0 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65  ter, the.** name
234c0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
234d0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
234e0 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
234f0 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a  ed in UTF-8 for.
23500 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
23510 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
23520 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71 6c 69   UTF-16 for sqli
23530 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
23540 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
23550 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
23560 74 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  t is the [databa
23570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
23580 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a  hat holds the.**
23590 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
235a0 20 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f   aggregate is to
235b0 20 62 65 20 61 64 64 65 64 20 6f 72 20 72 65 64   be added or red
235c0 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e  efined. If a sin
235d0 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  gle.** program u
235e0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
235f0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
23600 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  e internally, th
23610 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  en SQL.** functi
23620 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
23630 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
23640 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20  individually to 
23650 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a  each database.**
23660 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69   handle with whi
23670 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20  ch they will be 
23680 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
23690 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
236a0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
236b0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
236c0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a   to be created.*
236d0 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a  * or redefined..
236e0 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** The length of
236f0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
23700 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
23710 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  s, exclusive of 
23720 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72  the .** zero-ter
23730 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
23740 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
23750 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
23760 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
23770 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
23780 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
23790 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
237a0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
237b0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
237c0 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   an SQLITE_ERROR
237d0 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
237e0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
237f0 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  r is the number 
23800 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
23810 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
23820 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
23830 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69  te takes. If thi
23840 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
23850 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
23860 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
23870 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
23880 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
23890 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
238a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
238b0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
238c0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
238d0 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54   what .** [SQLIT
238e0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
238f0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
23900 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
23910 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
23920 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
23930 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
23940 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
23950 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
23960 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
23970 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
23980 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
23990 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
239a0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
239b0 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
239c0 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
239d0 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
239e0 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  It is allowed to
239f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
23a00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
23a10 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
23a20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
23a30 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
23a40 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
23a50 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
23a60 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
23a70 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
23a80 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74  ep..** When mult
23a90 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
23aa0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
23ab0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
23ac0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
23ad0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
23ae0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
23af0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
23b00 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
23b10 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
23b20 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
23b30 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
23b40 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
23b50 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20  ot care what.** 
23b60 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
23b70 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
23b80 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
23b90 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51  should be.** [SQ
23ba0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
23bb0 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   The fifth param
23bc0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
23bd0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
23be0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
23bf0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63  n.** of the func
23c00 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
23c10 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
23c20 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  nter using.** [s
23c30 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
23c40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
23c50 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
23c60 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
23c70 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
23c80 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
23c90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
23ca0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
23cb0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
23cc0 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20  ment the SQL.** 
23cd0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
23ce0 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
23cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
23d00 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
23d10 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ntation of.** th
23d20 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b  e xFunc callback
23d30 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
23d40 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
23d50 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
23d60 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
23d70 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
23d80 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
23d90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
23da0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
23db0 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e  n.** of xStep an
23dc0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
23dd0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
23de0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
23df0 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78   delete an.** ex
23e00 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
23e10 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
23e20 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
23e30 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
23e40 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a  on.** callback..
23e50 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d  **.** It is perm
23e60 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
23e70 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
23e80 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
23e90 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
23ea0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
23eb0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
23ec0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
23ed0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
23ee0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
23ef0 65 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20  ering perferred 
23f00 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
23f10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
23f20 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
23f30 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73  tation most clos
23f40 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
23f50 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
23f60 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
23f70 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
23f80 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23f90 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b  * {F16103} The [
23fa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23fb0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74  unction16()] int
23fc0 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65  erface behaves e
23fd0 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  xactly.**       
23fe0 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33     like [sqlite3
23ff0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
24000 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79  ()] in every way
24010 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a   except that it.
24020 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
24030 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63  rprets the zFunc
24040 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e  tionName argumen
24050 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t as.**         
24060 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24070 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
24080 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
24090 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20 20  d of as a.**    
240a0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
240b0 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
240c0 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75  ** {F16106} A su
240d0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
240e0 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
240f0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
24100 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
24110 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
24120 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
24130 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
24140 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
24150 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
24160 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24170 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
24180 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c      used to impl
24190 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
241a0 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77  nction named X w
241b0 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73  ith N parameters
241c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
241d0 20 68 61 76 69 6e 67 20 61 20 70 65 72 66 65 72   having a perfer
241e0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
241f0 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46  g of E..**.** {F
24200 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73  16109} A success
24210 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
24220 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24230 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
24240 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
24250 20 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20     replaces the 
24260 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76  P, F, S, and L v
24270 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70  alues from any p
24280 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a  rior calls with.
24290 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
242a0 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e  same D, X, N, an
242b0 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  d E values..**.*
242c0 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65 20 5b  * {F16112} The [
242d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
242e0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
242f0 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
24300 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
24310 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65     a return code
24320 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
24330 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75  R] if the SQL fu
24340 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  nction name X is
24350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e  .**          lon
24360 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74  ger than 255 byt
24370 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  es exclusive of 
24380 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
24390 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  tor..**.** {F161
243a0 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73  18} Either F mus
243b0 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20  t be NULL and S 
243c0 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
243d0 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20  LL or else F.** 
243e0 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
243f0 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
24400 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72   are NULL, other
24410 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  wise.**         
24420 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24430 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
24440 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75  E,P,F,S,L)] retu
24450 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  rns [SQLITE_ERRO
24460 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32  R]..**.** {F1612
24470 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
24480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
24490 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
244a0 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  e fails with an.
244b0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
244c0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
244d0 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65  E_BUSY] if there
244e0 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64   exist [prepared
244f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20   statements].** 
24500 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
24510 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
24520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24530 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  n] D..**.** {F16
24540 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
24550 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24560 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e  n(D,X,N,...)] in
24570 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
24580 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
24590 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20    error code of 
245a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
245b0 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73  f parameter N (s
245c0 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75  pecifying the nu
245d0 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
245e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
245f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
24600 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72  n being register
24610 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20  ed) is less.**  
24620 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20          than -1 
24630 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
24640 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  127..**.** {F161
24650 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f  27} When N is no
24660 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  n-negative, the 
24670 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
24680 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
24690 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
246a0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
246b0 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  s callbacks to b
246c0 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
246d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
246e0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
246f0 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
24700 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
24710 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
24720 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
24730 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
24740 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57 68 65  .** {F16130} Whe
24750 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
24760 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24770 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
24780 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
24790 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
247a0 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
247b0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
247c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
247d0 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
247e0 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65  X with any numbe
247f0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
24800 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57  **.** {F16133} W
24810 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
24820 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24830 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
24840 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
24850 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
24860 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
24870 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
24880 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20  ion X.**        
24890 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69    and when one i
248a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61  mplementation ha
248b0 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f  s N>=0 and the o
248c0 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a  ther has N=(-1).
248d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
248e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
248f0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e  ith a non-zero N
24900 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
24910 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57 68  *.** {F16136} Wh
24920 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
24930 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
24940 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
24950 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
24960 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
24970 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
24980 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
24990 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20  tion X with.**  
249a0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
249b0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
249c0 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20  ents N but with 
249d0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20  different.**    
249e0 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20        encodings 
249f0 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c  E, then the impl
24a00 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65  ementation where
24a10 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a   E matches the.*
24a20 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
24a30 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
24a40 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
24a50 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20 61 6e   {F16139} For an
24a60 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
24a70 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20  unction created 
24a80 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
24a90 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
24aa0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
24ab0 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65  ,E,P,0,S,L)] the
24ac0 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20   finializer.**  
24ad0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
24ae0 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62   L will always b
24af0 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c  e invoked exactl
24b00 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a  y once if the.**
24b10 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66            step f
24b20 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c  unction S is cal
24b30 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
24b40 74 69 6d 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  times..*/.int sq
24b50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24b60 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
24b70 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
24b80 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
24b90 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
24ba0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
24bb0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
24bc0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
24bd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
24be0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24bf0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
24c00 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
24c10 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
24c20 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
24c30 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
24c40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
24c50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
24c60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
24c70 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
24c80 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
24c90 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
24ca0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
24cb0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
24cc0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
24cd0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
24ce0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
24cf0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
24d00 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
24d10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
24d20 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
24d30 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
24d40 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
24d50 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
24d60 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
24d70 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36  Encodings {F1026
24d80 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  7}.**.** These c
24d90 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
24da0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
24db0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
24dc0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
24dd0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
24de0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
24df0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24e00 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
24e10 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
24e20 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
24e30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
24e40 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
24e50 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
24e60 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
24e70 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
24e80 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
24e90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24ea0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
24eb0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
24ec0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
24ed0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
24ee0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
24ef0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
24f00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
24f10 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
24f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
24f30 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e  bsolete Function
24f40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
24f50 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20  nctions are all 
24f60 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49  now obsolete.  I
24f70 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
24f80 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
24f90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
24fa0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
24fb0 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73  we continue to s
24fc0 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20  upport.** these 
24fd0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65  functions.  Howe
24fe0 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70  ver, new develop
24ff0 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68  ment projects sh
25000 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
25010 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
25020 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
25030 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
25040 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
25050 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
25060 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
25070 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
25080 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f  you want they do
25090 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
250a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
250b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
250c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
250d0 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
250e0 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
250f0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
25100 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
25110 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
25120 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
25130 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
25140 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69  void);.void sqli
25150 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
25160 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  up(void);.int sq
25170 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
25180 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
25190 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
251a0 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
251b0 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
251c0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
251d0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
251e0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
251f0 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a  es {F15100}.**.*
25200 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
25210 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25220 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
25230 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
25240 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
25250 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
25260 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
25270 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
25280 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
25290 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
252a0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
252b0 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
252c0 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
252d0 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
252e0 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
252f0 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
25300 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25310 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
25320 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25330 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
25340 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
25350 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
25360 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
25370 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
25380 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
25390 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
253a0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
253b0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
253c0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
253d0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
253e0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
253f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
25400 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
25410 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
25420 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
25430 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
25440 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
25450 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
25460 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25470 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
25480 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25490 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
254a0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
254b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
254c0 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  lumn_blob | sqli
254d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75  te3_column_* rou
254e0 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74 68  tines] except th
254f0 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  at .** these rou
25500 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
25510 67 6c 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  gle [sqlite3_val
25520 75 65 2a 5d 20 70 6f 69 6e 74 65 72 20 69 6e 73  ue*] pointer ins
25530 74 65 61 64 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  tead.** of an [s
25540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
25550 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
25560 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
25570 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
25580 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25590 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
255a0 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20  xtracts a UTF16 
255b0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
255c0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
255d0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
255e0 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
255f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25600 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
25610 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
25620 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
25630 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31  .** extract UTF1
25640 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
25650 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
25660 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
25670 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
25680 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
25690 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
256a0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
256b0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
256c0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
256d0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
256e0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
256f0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
25700 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
25710 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
25720 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
25730 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
25740 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
25750 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
25760 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
25770 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
25780 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66  ther.** words if
25790 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
257a0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
257b0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
257c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
257d0 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e  version is done.
257e0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
257f0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
25800 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  .  The .** [SQLI
25810 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
25820 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
25830 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
25840 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  ned..**.** Pleas
25850 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
25860 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
25870 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
25880 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
25890 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  is returned from
258a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
258b0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
258c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
258d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
258e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
258f0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
25900 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
25910 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
25920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
25930 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
25940 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
25950 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
25960 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
25970 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
25980 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a  ext16()].  .**.*
25990 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
259a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
259b0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
259c0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
259d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
259e0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73 71   supplied the sq
259f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61 72  lite3_value* par
25a00 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c 20  ameters..** Or, 
25a10 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  if the sqlite3_v
25a20 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20 63  alue* argument c
25a30 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  omes from the [s
25a40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
25a50 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  lue()].** interf
25a60 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65 20  ace, then these 
25a70 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
25a80 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
25a90 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a 2a  he same thread.*
25aa0 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c 69  * that ran [sqli
25ab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25ac0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e  ()]..**.**.** IN
25ad0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25ae0 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71  {F15103} The [sq
25af0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
25b00 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
25b10 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
25b20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25b30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
25b40 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64   into a blob and
25b50 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
25b60 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
25b70 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
25b80 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
25b90 2a 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b  * {F15106} The [
25ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
25bb0 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
25bc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
25bd0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
25be0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
25bf0 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20   blob or string 
25c00 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
25c10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
25c20 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
25c30 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
25c40 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
25c50 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
25c60 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
25c70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
25c80 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
25c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
25ca0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25cb0 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
25cc0 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
25cd0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
25ce0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
25cf0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
25d00 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
25d10 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
25d20 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
25d30 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
25d40 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
25d50 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
25d60 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
25d70 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
25d80 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
25d90 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25da0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
25db0 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
25dc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25dd0 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
25de0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25df0 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
25e00 0a 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65  .** {F15112} The
25e10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25e20 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
25e30 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
25e40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
25e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25e60 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
25e70 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
25e80 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
25e90 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
25ea0 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
25eb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20  .**.** {F15115} 
25ec0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
25ed0 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
25ee0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
25ef0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
25f00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25f10 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
25f20 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
25f30 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
25f40 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
25f50 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
25f60 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
25f70 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68  *.** {F15118} Th
25f80 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25f90 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72  _int64(V)] inter
25fa0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
25fb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
25fc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
25fd0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
25fe0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
25ff0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
26000 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
26010 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
26020 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32  er..**.** {F1512
26030 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
26040 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69  value_text(V)] i
26050 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
26060 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
26070 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
26080 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
26090 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
260a0 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20  d UTF-8 .**     
260b0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
260c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
260d0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
260e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d  ..**.** {F15124}
260f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
26100 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
26110 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
26120 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
26130 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
26140 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
26150 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26160 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
26170 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
26180 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
26190 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
261a0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
261b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
261c0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
261d0 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54 68  *.** {F15127} Th
261e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
261f0 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e  _text16be(V)] in
26200 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
26210 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26220 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
26230 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
26240 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26250 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
26260 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
26270 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
26280 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
26290 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
262a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
262b0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
262c0 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  5130} The [sqlit
262d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
262e0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
262f0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
26300 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
26310 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26320 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
26330 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
26340 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
26350 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  ned UTF-16 littl
26360 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  e-endian.**     
26370 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
26380 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
26390 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
263a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d  ..**.** {F15133}
263b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
263c0 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  lue_type(V)] int
263d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
263e0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
263f0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
26400 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
26410 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
26420 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
26430 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
26440 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
26450 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
26460 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
26470 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26480 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a  ] object V..**.*
26490 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b  * {F15136} The [
264a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
264b0 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69  meric_type(V)] i
264c0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
264d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
264e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
264f0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
26500 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65  either an intege
26510 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  r or.**         
26520 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
26530 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61  t value if it ca
26540 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20  n do so without 
26550 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  loss of.**      
26560 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c      information,
26570 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65   and returns one
26580 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
26590 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
265a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
265b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
265c0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
265d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
265e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
265f0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
26600 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
26610 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
26620 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74  object V after t
26630 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74  he conversion at
26640 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tempt..*/.const 
26650 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
26660 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
26670 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
26680 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
26690 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
266a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
266b0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
266c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
266d0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
266e0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
266f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
26700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
26710 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26720 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
26730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
26740 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
26750 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
26760 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
26770 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
26780 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
26790 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
267a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
267b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
267c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
267d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
267e0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
267f0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
26800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26810 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
26820 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
26830 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
26840 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26850 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
26860 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
26870 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26890 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
268a0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
268b0 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a  xt {F16210}.**.*
268c0 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
268d0 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74  tion of aggregat
268e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
268f0 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
26900 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20   to allocate.** 
26910 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  a structure for 
26920 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
26930 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69  ate.  .** The fi
26940 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
26950 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26960 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
26970 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64   is.** is called
26980 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
26990 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
269a0 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
269b0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
269c0 2a 20 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d  * zeros that mem
269d0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
269e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
269f0 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61  ..** On second a
26a00 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
26a10 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
26a20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26a30 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
26a40 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
26a50 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65  ction index, the
26a60 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
26a70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
26a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
26a90 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ** of the aggreg
26aa0 61 74 65 20 63 61 6e 20 75 73 65 20 74 68 65 20  ate can use the 
26ab0 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
26ac0 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
26ad0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
26ae0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
26af0 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
26b00 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
26b10 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
26b20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
26b30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
26b40 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
26b50 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
26b60 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
26b70 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
26b80 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
26b90 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
26ba0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  t.** parameter t
26bb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
26bc0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
26bd0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
26be0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
26bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
26c00 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
26c10 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
26c20 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
26c30 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
26c40 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
26c50 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
26c60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
26c70 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65  .** {F16211} The
26c80 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
26c90 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67  n of [sqlite3_ag
26ca0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
26cb0 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  C,N)] for.**    
26cc0 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c        a particul
26cd0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
26ce0 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
26cf0 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
26d00 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20  icular.**       
26d10 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61     context C) ca
26d20 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61  uses SQLite to a
26d30 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65  llocation N byte
26d40 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  s of memory,.** 
26d50 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68           zero th
26d60 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
26d70 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
26d80 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  to the allocatio
26d90 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
26da0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
26db0 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
26dc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
26dd0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
26de0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
26df0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
26e00 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
26e10 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
26e20 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
26e30 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {F16215} Secon
26e40 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
26e50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
26e60 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
26e70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26e80 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
26e90 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
26ea0 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
26eb0 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
26ec0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
26ed0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
26ee0 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
26ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
26f00 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
26f10 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
26f20 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
26f30 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65  .** {F16217} The
26f40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
26f50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
26f60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
26f70 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
26f80 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
26f90 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
26fa0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
26fb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
26fc0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
26fd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26fe0 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
26ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27000 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
27010 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
27020 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
27030 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
27040 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
27050 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
27060 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
27070 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
27080 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
27090 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
270a0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
270b0 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a  ons {F16240}.**.
270c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
270d0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
270e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
270f0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
27100 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
27110 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
27120 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
27130 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
27140 20 74 68 65 20 74 68 65 20 5b 73 71 6c 69 74 65   the the [sqlite
27150 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27160 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
27170 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27180 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
27190 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
271a0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
271b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
271c0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
271d0 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  n. {END}.**.** T
271e0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
271f0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
27200 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
27210 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
27220 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27230 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
27240 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
27250 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
27260 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73   {F16243} The [s
27270 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
27280 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (C)] interface r
27290 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
272a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
272b0 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20   P pointer from 
272c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
272d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
272e0 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
272f0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
27300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27310 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45  nction16(D,X,N,E
27320 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20  ,P,F,S,L)] call 
27330 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
27340 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
27350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  SQL function ass
27360 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a  ociated with .**
27370 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
27380 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a  e3_context] C..*
27390 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
273a0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
273b0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
273c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
273d0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
273e0 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a   Data {F16270}.*
273f0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
27400 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
27410 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
27420 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
27430 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
27440 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
27450 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
27460 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
27470 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
27480 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
27490 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
274a0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
274b0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
274c0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
274d0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
274e0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
274f0 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74  ociated meta-dat
27500 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
27510 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
27520 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
27530 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
27540 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
27550 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
27560 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
27570 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
27580 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
27590 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
275a0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
275b0 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74  ta-data associat
275c0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
275d0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
275e0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
275f0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
27600 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
27610 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
27620 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
27630 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
27640 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
27650 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
27660 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
27670 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
27680 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
27690 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
276a0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
276b0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
276c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
276d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
276e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
276f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
27700 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f  eta-data.** asso
27710 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
27720 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27730 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
27740 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
27750 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
27760 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27770 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
27780 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  .** If no meta-d
27790 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
277a0 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  r been set for t
277b0 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65  he Nth.** argume
277c0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
277d0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
277e0 6f 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  oresponding func
277f0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
27800 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  * has changed si
27810 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
27820 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20  a was set, then 
27830 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
27840 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ata().** returns
27850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
27860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
27870 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
27880 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
27890 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
278a0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
278b0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
278c0 72 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64 61  r as the meta-da
278d0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
278e0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
278f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27900 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
27910 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
27920 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
27930 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
27940 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
27950 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
27960 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
27970 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69  troyed. .** If i
27980 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
27990 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
279a0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
279b0 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69   .** function gi
279c0 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
279d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
279e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
279f0 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
27a00 2d 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  -data when the c
27a10 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
27a20 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
27a30 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
27a40 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
27a50 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
27a60 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
27a70 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
27a80 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
27a90 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
27aa0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
27ab0 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20  -data on.** any 
27ac0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
27ad0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
27ae0 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79   time.  The only
27af0 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73   guarantee.** is
27b00 20 74 68 61 74 20 74 68 65 20 64 65 73 74 72 75   that the destru
27b10 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
27b20 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
27b30 65 74 61 64 61 74 61 20 69 73 0a 2a 2a 20 64 72  etadata is.** dr
27b40 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  opped..**.** In 
27b50 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64  practice, meta-d
27b60 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
27b70 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
27b80 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
27b90 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
27ba0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
27bb0 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
27bc0 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
27bd0 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
27be0 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
27bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27c00 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
27c10 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
27c20 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
27c30 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
27c40 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27c50 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
27c60 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
27c70 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  72} The [sqlite3
27c80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
27c90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27ca0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
27cb0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65  *          to me
27cc0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
27cd0 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70  d with the Nth p
27ce0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
27cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
27d00 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63           whose c
27d10 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20  ontext is C, or 
27d20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
27d30 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   no metadata ass
27d40 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
27d50 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61      with that pa
27d60 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
27d70 46 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c  F16274} The [sql
27d80 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
27d90 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72  (C,N,P,D)] inter
27da0 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d  face assigns a m
27db0 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
27dc0 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f      pointer P to
27dd0 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
27de0 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
27df0 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74  nction with cont
27e00 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
27e10 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36  C..**.** {F16276
27e20 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
27e30 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
27e40 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
27e50 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
27e60 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69           which i
27e70 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70  s the metadata p
27e80 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69  ointer P followi
27e90 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ng a call to.** 
27ea0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27eb0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
27ec0 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c  N,P,D)] when SQL
27ed0 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
27ee0 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ld.**          t
27ef0 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a  he metadata..**.
27f00 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69  ** {F16277} SQLi
27f10 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
27f20 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61  d metadata for a
27f30 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  n SQL function p
27f40 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
27f50 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61       when the va
27f60 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61  lue of that para
27f70 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a  meter changes..*
27f80 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68  *.** {F16278} Wh
27f90 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  en [sqlite3_set_
27fa0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
27fb0 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  ] is invoked, th
27fc0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
27fd0 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c           is call
27fe0 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72  ed for any prior
27ff0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
28000 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
28010 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  me function.**  
28020 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
28030 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  C and parameter 
28040 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39  N..**.** {F16279
28050 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61  } SQLite will ca
28060 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66  ll destructors f
28070 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20  or any metadata 
28080 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a  it is holding.**
28090 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70            in a p
280a0 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61  articular [prepa
280b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
280c0 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20   when either.** 
280d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
280e0 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b  3_reset(S)] or [
280f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28100 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
28110 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
28120 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
28130 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
28140 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
28150 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
28160 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28170 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
28180 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
28190 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
281a0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
281b0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
281c0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
281d0 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a  or {F10280}.**.*
281e0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
281f0 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ial value for th
28200 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
28210 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
28220 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
28230 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
28240 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
28250 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
28260 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
28270 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
28280 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
28290 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
282a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
282b0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
282c0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
282d0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
282e0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
282f0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
28300 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  he .** SQLITE_TR
28310 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
28320 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
28330 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
28340 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
28350 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
28360 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
28370 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
28380 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28390 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
283a0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
283b0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
283c0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
283d0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
283e0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
283f0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
28400 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
28410 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
28420 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
28430 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
28440 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
28450 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
28460 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
28470 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28480 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
28490 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
284a0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
284b0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
284c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
284d0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
284e0 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
284f0 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a  tion {F16400}.**
28500 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
28510 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
28520 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
28530 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
28540 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
28550 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
28560 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
28570 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
28580 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
28590 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
285a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
285b0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
285c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
285d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
285e0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
285f0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
28600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28610 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
28620 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20  _bind_*] family 
28630 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  of functions use
28640 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c  d.** to bind val
28650 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
28660 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
28670 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
28680 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a  * Refer to the.*
28690 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
286a0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
286b0 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74  ind_* documentat
286c0 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69  ion] for.** addi
286d0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
286e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
286f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28700 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
28710 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
28720 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
28730 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
28740 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
28750 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
28760 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
28770 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
28780 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
28790 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
287a0 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
287b0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
287c0 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65  rameter. .** The
287d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
287e0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65 72 66  zeroblob() inerf
287f0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
28800 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
28810 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
28820 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
28830 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
28840 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
28850 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
28860 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
28870 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
28880 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
28890 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
288a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
288b0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
288c0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
288d0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
288e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
288f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
28900 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28910 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
28920 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
28930 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
28940 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28950 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
28960 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
28970 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
28980 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
28990 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
289a0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
289b0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
289c0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
289d0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
289e0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
289f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
28a00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
28a10 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
28a20 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
28a30 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
28a40 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
28a50 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65  ge.  SQLite inte
28a60 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
28a70 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
28a80 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
28a90 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
28aa0 73 20 55 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a  s UTF8. SQLite.*
28ab0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
28ac0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
28ad0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
28ae0 72 31 36 28 29 20 61 73 20 55 54 46 31 36 20 69  r16() as UTF16 i
28af0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
28b00 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20   order.  If the 
28b10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28b20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
28b30 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
28b40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28b50 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
28b60 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
28b70 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
28b80 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
28b90 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
28ba0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
28bb0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
28bc0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
28bd0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28bf0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
28c00 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28c10 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
28c20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
28c30 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
28c40 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
28c50 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
28c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
28c70 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
28c80 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  e..** The sqlite
28c90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
28ca0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
28cb0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
28cc0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
28cd0 20 63 6f 70 79 20 70 72 69 76 61 74 65 20 63 6f   copy private co
28ce0 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
28cf0 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
28d00 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
28d10 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
28d20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
28d30 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
28d40 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
28d50 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
28d60 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
28d70 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  harm..** The sql
28d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
28d90 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
28da0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
28db0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
28dc0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
28dd0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
28de0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
28df0 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c  tion.  By defaul
28e00 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
28e10 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
28e20 52 52 4f 52 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  RROR. .**.** The
28e30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28e40 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
28e50 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
28e60 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  .** to throw an 
28e70 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
28e80 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
28e90 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e  r BLOB is to lon
28ea0 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e  g.** to represen
28eb0 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
28ec0 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
28ed0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73  nterface.** caus
28ee0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
28ef0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  ow an exception 
28f00 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
28f10 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  the a.** memory 
28f20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
28f30 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
28f40 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
28f50 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
28f60 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
28f70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
28f80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28f90 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
28fa0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
28fb0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
28fc0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
28fd0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
28fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28ff0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
29000 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29010 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
29020 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29030 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29040 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
29050 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
29060 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
29070 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
29080 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
29090 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
290a0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
290b0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
290c0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
290d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
290e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
290f0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  be NULL..**.** T
29100 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29110 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
29120 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
29130 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ), .** sqlite3_r
29140 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
29150 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
29160 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
29170 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
29180 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
29190 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
291a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
291b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
291c0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
291d0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
291e0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
291f0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
29200 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
29210 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
29220 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
29230 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
29240 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61  ly..** SQLite ta
29250 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
29260 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
29270 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
29280 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
29290 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
292a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
292b0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66  nterfaces..** If
292c0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
292d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
292e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
292f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
29300 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
29310 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
29320 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
29330 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a   2nd parameter .
29340 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
29350 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
29360 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
29370 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29380 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
29390 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
293a0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
293b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
293c0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
293d0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
293e0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
293f0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
29400 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
29410 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
29420 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
29430 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
29440 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
29450 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29460 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29470 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29480 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
29490 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
294a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
294b0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
294c0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
294d0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
294e0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
294f0 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73  text or blob res
29500 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
29510 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
29520 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
29530 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
29540 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
29550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29560 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
29570 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29580 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
29590 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
295a0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
295b0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73  hen.** SQLite as
295c0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
295d0 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
295e0 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73  lt is constant s
295f0 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73  pace and.** does
29600 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70   not copy the sp
29610 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65  ace or call a de
29620 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
29630 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
29640 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
29650 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
29660 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29670 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29680 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29690 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
296a0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
296b0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
296c0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
296d0 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
296e0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
296f0 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
29700 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
29710 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
29720 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
29730 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
29740 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
29750 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29760 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
29770 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
29780 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
29790 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
297a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
297b0 20 63 6f 70 79 20 74 68 65 20 5b 73 71 6c 69 74   copy the [sqlit
297c0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
297d0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
297e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
297f0 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  er.  The.** sqli
29800 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29810 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
29820 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
29830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
29840 0a 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c  .** so that [sql
29850 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
29860 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
29870 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
29880 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
29890 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
298a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
298b0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
298c0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20  out harm..**.** 
298d0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
298e0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
298f0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
29900 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a 2a  ferent thread .*
29910 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
29920 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
29930 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29940 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
29950 72 65 63 69 65 76 65 64 0a 2a 2a 20 74 68 65 20  recieved.** the 
29960 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
29970 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
29980 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
29990 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ined..**.** INVA
299a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
299b0 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 75  16403} The defau
299c0 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  lt return value 
299d0 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e  from any SQL fun
299e0 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a  ction is NULL..*
299f0 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54 68  *.** {F16406} Th
29a00 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
29a10 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
29a20 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
29a30 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
29a40 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
29a50 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
29a60 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61 74 20   be a blob that 
29a70 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20  is N bytes.**   
29a80 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68         in length
29a90 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e   and with conten
29aa0 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  t pointed to by 
29ab0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39  V..**.** {F16409
29ac0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
29ad0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56  esult_double(C,V
29ae0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
29af0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
29b00 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
29b10 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
29b20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69  to be the floati
29b30 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56  ng point value V
29b40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d  ..**.** {F16412}
29b50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
29b60 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e  sult_error(C,V,N
29b70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
29b80 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
29b90 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
29ba0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
29bb0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
29bc0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
29bd0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
29be0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e  SQLITE_ERROR] an
29bf0 64 20 61 20 55 54 46 38 20 65 72 72 6f 72 20 6d  d a UTF8 error m
29c00 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72  essage copied fr
29c10 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a  om V up to the.*
29c20 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
29c30 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e   zero byte or un
29c40 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20  til N bytes are 
29c50 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73  read if N is pos
29c60 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  itive..**.** {F1
29c70 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6415} The [sqlit
29c80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29c90 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  6(C,V,N)] interf
29ca0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
29cb0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
29cc0 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
29cd0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
29ce0 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
29cf0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
29d00 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
29d10 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 31 36  ROR] and a UTF16
29d20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29d30 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
29d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
29d50 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
29d60 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
29d70 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
29d80 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
29d90 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
29da0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
29db0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38  e..**.** {F16418
29dc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
29dd0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
29de0 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
29df0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
29e00 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
29e10 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
29e20 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
29e30 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
29e40 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
29e50 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
29e60 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
29e70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
29e80 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
29e90 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  F16421} The [sql
29ea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29eb0 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
29ec0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
29ed0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
29ee0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
29ef0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
29f00 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
29f10 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
29f20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
29f30 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
29f40 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
29f50 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
29f60 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68 65 20  ** {F16424} The 
29f70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
29f80 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
29f90 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
29fa0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
29fb0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
29fc0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
29fd0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
29fe0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
29ff0 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
2a000 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
2a010 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
2a020 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
2a030 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  F16427} The [sql
2a040 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2a050 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2a060 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2a070 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2a080 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2a090 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
2a0a0 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
2a0b0 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
2a0c0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
2a0d0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
2a0e0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
2a0f0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2a100 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2a110 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2a120 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2a130 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
2a140 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33  V..**.** {F16433
2a150 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2a160 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
2a170 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2a180 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a190 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2a1a0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
2a1b0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e NULL..**.** {F
2a1c0 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
2a1d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2a1e0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
2a1f0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
2a200 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2a210 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
2a220 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
2a230 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20   UTF8 string.** 
2a240 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74 68           V up th
2a250 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2a260 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e 20  zero or until N 
2a270 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
2a280 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  f N.**          
2a290 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
2a2a0 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68 65 20  ** {F16439} The 
2a2b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2a2c0 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
2a2d0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
2a2e0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2a2f0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
2a300 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
2a310 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6e 61   be the UTF16 na
2a320 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
2a330 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2a340 6e 67 20 20 56 20 75 70 20 74 68 72 6f 75 67 68  ng  V up through
2a350 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2a360 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
2a370 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a 2a   are read if N.*
2a380 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70 6f  *          is po
2a390 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
2a3a0 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16442} The [sqli
2a3b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a3c0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6be(C,V,N,D)] in
2a3d0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2a3e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a3f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2a400 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2a410 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d 65   the UTF16 big-e
2a420 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2a430 20 20 73 74 72 69 6e 67 20 20 56 20 75 70 20 74    string  V up t
2a440 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2a450 20 7a 65 72 6f 20 6f 72 20 75 6e 74 69 6c 20 4e   zero or until N
2a460 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
2a470 69 66 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20  if N.**         
2a480 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
2a490 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65  .** {F16445} The
2a4a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2a4b0 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
2a4c0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
2a4d0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
2a4e0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
2a4f0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
2a500 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36   to be the UTF16
2a510 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
2a520 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2a530 67 20 20 56 20 75 70 20 74 68 72 6f 75 67 68 20  g  V up through 
2a540 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 6f  the first zero o
2a550 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73 20  r until N bytes 
2a560 61 72 65 20 72 65 61 64 20 69 66 20 4e 0a 2a 2a  are read if N.**
2a570 20 20 20 20 20 20 20 20 20 20 69 73 20 70 6f 73            is pos
2a580 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  itive..**.** {F1
2a590 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  6448} The [sqlit
2a5a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a5b0 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
2a5c0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
2a5d0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
2a5e0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
2a5f0 20 43 20 74 6f 20 62 65 20 5b 73 71 6c 69 74 65   C to be [sqlite
2a600 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2a610 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31  V..**.** {F16451
2a620 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2a630 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
2a640 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2a650 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2a660 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2a670 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2a680 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74  C to be an N-byt
2a690 65 20 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65  e blob of all ze
2a6a0 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ros..**.** {F164
2a6b0 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  54} The [sqlite3
2a6c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d  _result_error()]
2a6d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2a6e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a  sult_error16()].
2a6f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2a700 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f  rfaces make a co
2a710 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f  py of their erro
2a720 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2a730 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  s before.**     
2a740 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a       returning..
2a750 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49  **.** {F16457} I
2a760 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
2a770 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
2a780 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2a790 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
2a7a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a7b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a7c0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
2a7d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a7e0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
2a7f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2a800 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a810 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
2a820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2a830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a840 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
2a850 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20  is the constant 
2a860 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a  [SQLITE_STATIC].
2a870 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2a880 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69   no destructor i
2a890 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e  s ever called on
2a8a0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61   the pointer V a
2a8b0 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  nd SQLite.**    
2a8c0 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68        assumes th
2a8d0 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c  at V is immutabl
2a8e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30  e..**.** {F16460
2a8f0 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
2a900 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
2a910 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2a920 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
2a930 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2a940 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a950 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
2a960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a970 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
2a980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2a990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a9a0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
2a9b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2a9c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2a9d0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2a9e0 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
2a9f0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nt.**          [
2aa00 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2aa10 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72  ] then the inter
2aa20 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f  faces makes a co
2aa30 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2aa40 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66        content of
2aa50 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74   V and retains t
2aa60 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b  he copy..**.** {
2aa70 46 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44  F16463} If the D
2aa80 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
2aa90 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2aaa0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
2aab0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2aac0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2aad0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
2aae0 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
2aaf0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2ab00 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2ab10 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2ab20 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
2ab30 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
2ab40 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2ab50 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
2ab60 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65  ,V,N,D)] is some
2ab70 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
2ab80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
2ab90 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
2aba0 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20  ITE_STATIC] and 
2abb0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2abc0 54 5d 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20  T] then .**     
2abd0 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c       SQLite will
2abe0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
2abf0 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20  ructor D with V 
2ac00 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  as its only argu
2ac10 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
2ac20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2ac30 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56  ished with the V
2ac40 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20   value..*/.void 
2ac50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2ac60 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2ac70 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2ac80 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2ac90 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2aca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2acb0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
2acc0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
2acd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2ace0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2acf0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2ad00 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
2ad10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ad20 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
2ad30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2ad40 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
2ad50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2ad60 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2ad70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ad80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2ad90 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2ada0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
2adb0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2adc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2add0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
2ade0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2adf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ae00 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
2ae10 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2ae20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2ae30 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
2ae40 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2ae50 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
2ae60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2ae70 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
2ae80 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2ae90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
2aea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2aeb0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2aec0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2aed0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2aee0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
2aef0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2af00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2af10 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2af20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2af30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2af40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2af50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2af60 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2af70 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2af80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2af90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2afa0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2afb0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2afc0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2afd0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
2afe0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2aff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2b000 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2b010 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
2b020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b030 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2b040 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
2b050 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
2b060 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30  equences {F16600
2b070 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  }.**.** These fu
2b080 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
2b090 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
2b0a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2b0b0 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  to the.** [sqlit
2b0c0 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63  e3*] handle spec
2b0d0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2b0e0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a  st argument. .**
2b0f0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
2b100 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
2b110 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
2b120 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
2b130 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
2b140 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b150 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
2b160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b170 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
2b180 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
2b190 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
2b1a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b1b0 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61  n16(). In all ca
2b1c0 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
2b1d0 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
2b1e0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2b1f0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2b200 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2b210 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
2b220 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
2b230 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2b240 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
2b250 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  E] or [SQLITE_UT
2b260 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
2b270 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
2b280 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
2b290 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
2b2a0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
2b2b0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
2b2c0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
2b2d0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
2b2e0 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54  tle-endian or UT
2b2f0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20  F-16 big-endian 
2b300 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
2b310 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
2b320 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
2b330 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
2b340 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
2b350 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
2b360 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
2b370 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
2b380 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
2b390 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
2b3a0 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  TF16 in the nati
2b3b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66  ve byte order of
2b3c0 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
2b3d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  er..**.** A poin
2b3e0 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20  ter to the user 
2b3f0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
2b400 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2b410 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20  as the fifth.** 
2b420 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74  argument.  If it
2b430 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
2b440 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
2b450 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
2b460 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2b470 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
2b480 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
2b490 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63  anymore)..** Eac
2b4a0 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69  h time the appli
2b4b0 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  cation.** suppli
2b4c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
2b4d0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
2b4e0 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
2b4f0 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
2b500 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68  as.** the fourth
2b510 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2b520 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b530 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71  ation() or.** sq
2b540 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b550 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74  lation16() as it
2b560 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2b570 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  r..**.** The rem
2b580 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
2b590 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
2b5a0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
2b5b0 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
2b5c0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
2b5d0 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
2b5e0 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
2b5f0 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
2b600 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
2b610 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
2b620 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
2b630 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
2b640 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b650 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
2b660 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65  tered. {END} The
2b670 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2b680 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
2b690 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
2b6a0 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
2b6b0 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
2b6c0 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72  ve if.** the fir
2b6d0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
2b6e0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
2b6f0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
2b700 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  n the second.** 
2b710 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
2b720 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
2b730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2b740 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b750 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
2b760 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
2b770 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
2b780 2a 2a 20 65 78 63 61 70 74 20 74 68 61 74 20 69  ** excapt that i
2b790 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
2b7a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2b7b0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2b7c0 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
2b7d0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
2b7e0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
2b7f0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
2b800 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
2b810 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
2b820 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
2b830 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2b840 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
2b850 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
2b860 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b870 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74  _v2()..** Collat
2b880 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
2b890 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20  ed when.** they 
2b8a0 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
2b8b0 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
2b8c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
2b8d0 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
2b8e0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
2b8f0 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
2b900 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63  base handle is c
2b910 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2b920 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2b930 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2b940 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20  .**.** {F16603} 
2b950 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2b960 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  l to the.**     
2b970 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2b980 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2b990 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20  2(B,X,E,P,F,D)] 
2b9a0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20  interface.**    
2b9b0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20        registers 
2b9c0 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68  function F as th
2b9d0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
2b9e0 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a  ction used to.**
2b9f0 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d            implem
2ba00 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20  ent collation X 
2ba10 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
2ba20 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
2ba30 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
2ba40 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
2ba50 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ding E..**.** {F
2ba60 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
2ba70 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
2ba80 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
2ba90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2baa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2bab0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
2bac0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
2bad0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
2bae0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
2baf0 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
2bb00 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
2bb10 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
2bb20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2bb30 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
2bb40 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
2bb50 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
2bb60 46 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  F16606} Successi
2bb70 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
2bb80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bb90 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
2bba0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
2bbb0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
2bbc0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
2bbd0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
2bbe0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
2bbf0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
2bc00 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
2bc10 20 7b 46 31 36 36 30 39 7d 20 54 68 65 20 64 65   {F16609} The de
2bc20 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73  structor D in [s
2bc30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2bc40 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
2bc50 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
2bc60 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c       is not NULL
2bc70 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c   then it is call
2bc80 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
2bc90 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20   P when the.**  
2bca0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
2bcb0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
2bcc0 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e  opped by SQLite.
2bcd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20  .**.** {F16612} 
2bce0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
2bcf0 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
2bd00 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c  when it is overl
2bd10 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  oaded..**.** {F1
2bd20 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6615} A collatin
2bd30 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
2bd40 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64  opped when the d
2bd50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bd60 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
2bd70 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
2bd80 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2bd90 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d  ..**.** {F16618}
2bda0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69   The pointer P i
2bdb0 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
2bdc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
2bdd0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
2bde0 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73           is pass
2bdf0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
2be00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2be10 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69  r to the compari
2be20 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
2be30 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
2be40 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
2be50 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a  vocations of F..
2be60 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41  **.** {F16621} A
2be70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2be80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2be90 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69  on(B,X,E,P,F)] i
2bea0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
2beb0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
2bec0 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  s a call to [sql
2bed0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2bee0 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68  ation_v2()] with
2bef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2bf00 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73   same parameters
2bf10 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74   and a NULL dest
2bf20 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ructor..**.** {F
2bf30 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67  16624} Following
2bf40 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61   a [sqlite3_crea
2bf50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2bf60 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a  B,X,E,P,F,D)],.*
2bf70 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
2bf80 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61  e uses the compa
2bf90 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46  rison function F
2bfa0 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f   for all text co
2bfb0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
2bfc0 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20       operations 
2bfd0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
2bfe0 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65  nection] B on te
2bff0 78 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a  xt values that.*
2c000 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74  *          use t
2c010 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  he collating seq
2c020 75 65 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a  uence name X..**
2c030 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20 54 68 65  .** {F16627} The
2c040 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c050 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58  _collation16(B,X
2c060 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74  ,E,P,F)] works t
2c070 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
2c080 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f      as [sqlite3_
2c090 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2c0a0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63  (B,X,E,P,F)] exc
2c0b0 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ept that the.** 
2c0c0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
2c0d0 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64  on name X is und
2c0e0 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31  erstood as UTF-1
2c0f0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
2c100 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2c110 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54     instead of UT
2c120 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  F-8..**.** {F166
2c130 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  30} When multipl
2c140 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
2c150 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ctions are avail
2c160 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d  able for the sam
2c170 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2c180 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
2c190 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73  , SQLite chooses
2c1a0 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74   the one whose t
2c1b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
2c1c0 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65           require
2c1d0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2c1e0 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  nt of conversion
2c1f0 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c   from the defaul
2c200 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  t.**          te
2c210 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  xt encoding of t
2c220 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
2c230 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2c240 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
2c250 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2c260 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2c270 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c280 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2c290 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2c2a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2c2b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2c2c0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2c2d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c2e0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2c2f0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2c300 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2c310 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2c320 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2c330 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2c340 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2c350 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
2c360 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2c370 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2c380 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2c390 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
2c3a0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2c3b0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2c3c0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2c3d0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2c3e0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2c3f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2c400 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2c410 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c420 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
2c430 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ed Callbacks {F1
2c440 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  6700}.**.** To a
2c450 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2c460 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2c470 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2c480 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2c490 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2c4a0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2c4b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2c4c0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2c4d0 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
2c4e0 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
2c4f0 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
2c500 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
2c510 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2c520 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
2c530 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
2c540 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
2c550 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
2c560 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2c570 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
2c580 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
2c590 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
2c5a0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2c5b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
2c5c0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
2c5d0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b  oded in UTF-8. {
2c5e0 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74  F16703} If sqlit
2c5f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2c600 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2c610 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72   the names.** ar
2c620 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2c630 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2c640 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2c650 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
2c660 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
2c670 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74  places any exist
2c680 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ing callback..**
2c690 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
2c6a0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2c6b0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
2c6c0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
2c6d0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
2c6e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2c6f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
2c700 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
2c710 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
2c720 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2c730 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
2c740 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
2c750 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65  tabase.** handle
2c760 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
2c770 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2c780 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2c790 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  * [SQLITE_UTF16B
2c7a0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2c7b0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
2c7c0 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20  ing the most.** 
2c7d0 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
2c7e0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
2c7f0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
2c800 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54  n required..** T
2c810 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2c820 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2c830 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
2c840 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2c850 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
2c860 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2c870 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
2c880 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
2c890 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
2c8a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2c8b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
2c8c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c8d0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
2c8e0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
2c8f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2c900 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
2c910 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2c920 46 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73  F16702} A succes
2c930 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2c940 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2c950 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a  needed(D,P,F)].*
2c960 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2c970 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2c980 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29  _needed16(D,P,F)
2c990 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20  ] causes.**     
2c9a0 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
2c9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2c9c0 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62   to invoke callb
2c9d0 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74  ack F with first
2c9e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
2c9f0 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
2ca00 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d  r it needs a com
2ca10 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
2ca20 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20   for a.**       
2ca30 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
2ca40 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f  uence that it do
2ca50 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75  es not know abou
2ca60 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34  t..**.** {F16704
2ca70 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75  } Each successfu
2ca80 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2ca90 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2caa0 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ded()] or.**    
2cab0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2cac0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2cad0 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  6()] overrides t
2cae0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69  he callback regi
2caf0 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
2cb00 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
2cb10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cb20 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61  ion] by prior ca
2cb30 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  lls to either.**
2cb40 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2cb50 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  ace..**.** {F167
2cb60 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  06} The name of 
2cb70 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f  the requested co
2cb80 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2cb90 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a   passed in the.*
2cba0 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70  *          4th p
2cbb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2cbc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55  callback is in U
2cbd0 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c  TF-8 if the call
2cbe0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
2cbf0 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20   was registered 
2cc00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
2cc10 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2cc20 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
2cc30 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20     is in UTF-16 
2cc40 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2cc50 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r if the callbac
2cc60 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  k was.**        
2cc70 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69    registered usi
2cc80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
2cc90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2cca0 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74  ]..**.** .*/.int
2ccb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2ccc0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
2ccd0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
2cce0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2ccf0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
2cd00 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
2cd10 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
2cd20 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2cd30 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
2cd40 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
2cd50 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2cd60 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
2cd70 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
2cd80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
2cd90 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
2cda0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
2cdb0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
2cdc0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
2cdd0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
2cde0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
2cdf0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
2ce00 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2ce10 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2ce20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2ce30 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2ce40 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2ce50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
2ce60 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ce70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ce80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2ce90 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2cea0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2ceb0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2cec0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
2ced0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
2cee0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
2cef0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
2cf00 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
2cf10 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
2cf20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
2cf30 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
2cf40 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
2cf50 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
2cf60 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2cf70 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
2cf80 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2cf90 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2cfa0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2cfb0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2cfc0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2cfd0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2cfe0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
2cff0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2d000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d010 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2d020 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2d030 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2d040 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2d050 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
2d060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d070 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
2d080 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
2d090 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d  rt Time {F10530}
2d0a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d0b0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
2d0c0 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68  ion.** causes th
2d0d0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
2d0e0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
2d0f0 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
2d100 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
2d110 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
2d120 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
2d130 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2d140 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
2d150 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
2d160 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
2d170 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a  requests with .*
2d180 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
2d190 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
2d1a0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
2d1b0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
2d1c0 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65  to .** the neare
2d1d0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
2d1e0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2d1f0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
2d200 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75  ctually .** requ
2d210 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
2d220 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2d230 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2d240 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
2d250 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2d260 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2d270 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2d280 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2d290 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2d2a0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
2d2b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2d2c0 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20  ** {F10533} The 
2d2d0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
2d2e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76  )] interface inv
2d2f0 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a  okes the xSleep.
2d300 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68  **          meth
2d310 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
2d320 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56  t [sqlite3_vfs|V
2d330 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  FS] in order to.
2d340 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70  **          susp
2d350 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  end execution of
2d360 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2d370 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74  ead for at least
2d380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d  .**          M m
2d390 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a  illiseconds..**.
2d3a0 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68 65 20  ** {F10536} The 
2d3b0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
2d3c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2d3d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2d3e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  of.**          m
2d3f0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2d400 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65  leep actually re
2d410 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f  quested of the o
2d420 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20  perating.**     
2d430 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69       system, whi
2d440 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  ch might be larg
2d450 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61  er than the para
2d460 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20  meter M..*/.int 
2d470 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
2d480 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d490 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68  REF:  Name Of Th
2d4a0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2d4b0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2d4c0 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F10310}.**.** 
2d4d0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2d4e0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2d4f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2d500 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2d510 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2d520 6f 6c 64 65 72 20 28 61 2e 6b 61 2e 20 64 69 72  older (a.ka. dir
2d530 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
2d540 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
2d550 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2d560 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70  SQLite will be p
2d570 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2d580 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69  rectory.  If thi
2d590 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
2d5a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
2d5b0 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20  hen SQLite does 
2d5c0 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2d5d0 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70  appropriate temp
2d5e0 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69  orary.** file di
2d5f0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2d600 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2d610 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2d620 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74  iable once a dat
2d630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d640 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65  .** has been ope
2d650 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65  ned.  It is inte
2d660 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2d670 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2d680 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2d690 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2d6a0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2d6b0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2d6c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2d6d0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2d6e0 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75  all and remain u
2d6f0 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66  nchanged thereaf
2d700 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ter..*/.SQLITE_E
2d710 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2d720 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2d730 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2d740 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65  REF:  Test To Se
2d750 65 20 49 66 20 54 68 65 20 44 61 74 61 62 61 73  e If The Databas
2d760 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d  e Is In Auto-Com
2d770 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30  mit Mode {F12930
2d780 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
2d790 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2d7a0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  it() interfaces 
2d7b0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2d7c0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2d7d0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2d7e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2d7f0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2d800 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2d810 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2d820 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
2d830 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66   is on.** by def
2d840 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  ault.  Autocommi
2d850 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2d860 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2d870 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
2d880 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2d890 20 72 65 65 6e 61 62 6c 65 64 20 62 79 20 61 20   reenabled by a 
2d8a0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2d8b0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2d8c0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2d8d0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2d8e0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2d8f0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2d900 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2d910 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69  ctions (errors i
2d920 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
2d930 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
2d940 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  IOERR], .** [SQL
2d950 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2d960 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2d970 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2d980 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2d990 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2d9a0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2d9b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2d9c0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2d9d0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53  ** find out if S
2d9e0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2d9f0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2da00 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2da10 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2da20 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2da30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2da40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2da50 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20  ** {F12931} The 
2da60 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74  [sqlite3_get_aut
2da70 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65  ocommit(D)] inte
2da80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
2da90 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20  n-zero or.**    
2daa0 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68        zero if th
2dab0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2dac0 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20  ection] D is or 
2dad0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2dae0 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  mmit.**         
2daf0 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76   mode, respectiv
2db00 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ely..**.** {F129
2db10 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  32} Autocommit m
2db20 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
2db30 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ault..**.** {F12
2db40 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  933} Autocommit 
2db50 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2db60 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
2db70 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
2db80 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  nt..**.** {F1293
2db90 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  4} Autocommit mo
2dba0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
2dbb0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43   a successful [C
2dbc0 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
2dbd0 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ACK].**         
2dbe0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a   statement..** .
2dbf0 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
2dc00 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33  S:.***.** {U1293
2dc10 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  6} If another th
2dc20 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
2dc30 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
2dc40 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
2dc50 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  se.**          c
2dc60 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
2dc70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2dc80 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
2dc90 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2dca0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
2dcb0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
2dcc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2dcd0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
2dce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dcf0 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61 74  F:  Find The Dat
2dd00 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2dd10 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2dd20 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a  ment {F13120}.**
2dd30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2dd40 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
2dd50 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
2dd60 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61  he [sqlite3*] da
2dd70 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
2dd80 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65   which a.** [pre
2dd90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dda0 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65   belongs..** The
2ddb0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
2ddc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2ddd0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a  ite3_db_handle.*
2dde0 2a 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61  * is the same da
2ddf0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68  tabase handle th
2de00 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69  at was.** the fi
2de10 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2de20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2de30 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2de40 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68  s variants.** th
2de50 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63  at was used to c
2de60 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
2de70 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
2de80 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e   place..**.** IN
2de90 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2dea0 7b 46 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71  {F13123} The [sq
2deb0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2dec0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2ded0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2dee0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
2def0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2df00 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  nection] associa
2df10 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ted with.**     
2df20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2df30 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2df40 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2df50 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
2df60 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a  e3_stmt*);.../*.
2df70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2df80 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
2df90 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2dfa0 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d  llbacks {F12950}
2dfb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2dfc0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2dfd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2dfe0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2dff0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2e000 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2e010 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2e020 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a   is committed..*
2e030 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2e040 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2e050 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2e060 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2e070 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2e080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e090 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2e0a0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
2e0b0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2e0c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2e0d0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2e0e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2e0f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2e100 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2e110 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a   is committed..*
2e120 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
2e130 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2e140 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2e150 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
2e160 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2e170 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e180 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2e190 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72  ..** The pArg ar
2e1a0 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
2e1b0 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74   through.** to t
2e1c0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
2e1d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
2e1e0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
2e1f0 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75  unction .** retu
2e200 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
2e210 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2e220 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2e230 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2e240 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
2e250 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
2e260 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
2e270 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c   its.** pArg val
2e280 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2e290 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
2e2a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2e2b0 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61  ** Registering a
2e2c0 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
2e2d0 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
2e2e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  back..**.** For 
2e2f0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2e300 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
2e310 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
2e320 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a  to have been .**
2e330 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
2e340 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
2e350 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
2e360 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
2e370 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
2e380 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
2e390 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
2e3a0 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
2e3b0 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
2e3c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
2e3d0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
2e3e0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
2e3f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2e400 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2e410 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
2e420 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
2e430 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  sed..** The roll
2e440 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
2e450 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
2e460 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2e470 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
2e480 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
2e490 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
2e4a0 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20  ed non-zero..** 
2e4b0 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20  <todo> Check on 
2e4c0 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  this </todo>.**.
2e4d0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70  ** These are exp
2e4e0 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
2e4f0 61 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62  aces and are sub
2e500 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
2e510 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2e520 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d  :.**.** {F12951}
2e530 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2e540 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
2e550 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
2e560 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
2e570 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
2e580 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
2e590 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
2e5a0 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
2e5b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
2e5c0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
2e5d0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
2e5e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2e5f0 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54 68  *.** {F12952} Th
2e600 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
2e610 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
2e620 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e630 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20   the P.**       
2e640 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d     argument from
2e650 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2e660 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ll with the same
2e670 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64   .**          [d
2e680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e690 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c  on ] D , or NULL
2e6a0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
2e6b0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ll.**          f
2e6c0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2e6d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e6e0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2e6f0 46 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c  F12953} Each cal
2e700 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2e710 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  mmit_hook()] ove
2e720 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
2e730 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
2e740 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
2e750 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
2e760 2a 20 7b 46 31 32 39 35 34 7d 20 49 66 20 74 68  * {F12954} If th
2e770 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
2e780 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
2e790 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
2e7a0 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
2e7b0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
2e7c0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
2e7d0 73 20 63 61 6e 63 65 6c 6c 65 64 20 61 6e 64 20  s cancelled and 
2e7e0 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
2e7f0 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
2e800 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
2e810 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a  ction commits..*
2e820 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66  *.** {F12955} If
2e830 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c   the commit call
2e840 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
2e850 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63  -zero then the c
2e860 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20  ommit is.**     
2e870 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69       converted i
2e880 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
2e890 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54  **.** {F12961} T
2e8a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
2e8b0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
2e8c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
2e8d0 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
2e8e0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
2e8f0 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
2e900 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
2e910 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
2e920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
2e930 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73  ransaction rolls
2e940 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61   back on [databa
2e950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2e960 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d  ..**.** {F12962}
2e970 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f   The [sqlite3_ro
2e980 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
2e990 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
2e9a0 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20  turns the P.**  
2e9b0 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
2e9c0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
2e9d0 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65  us call with the
2e9e0 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20   same .**       
2e9f0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
2ea00 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72  nection ] D , or
2ea10 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
2ea20 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
2ea30 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
2ea40 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20 63  ular [database c
2ea50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2ea60 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63  .** {F12963} Eac
2ea70 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
2ea80 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2ea90 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
2eaa0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
2eab0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2eac0 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
2ead0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34  s..**.** {F12964
2eae0 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
2eaf0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
2eb00 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
2eb10 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
2eb20 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
2eb30 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
2eb40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
2eb50 63 65 6c 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  celled and no ca
2eb60 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
2eb70 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
2eb80 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
2eb90 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a   rolls back..*/.
2eba0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2ebb0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
2ebc0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
2ebd0 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
2ebe0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
2ebf0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
2ec00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
2ec10 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2ec20 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
2ec30 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
2ec40 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
2ec50 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12970}.**.** The
2ec60 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2ec70 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2ec80 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 20  .** registers a 
2ec90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2eca0 6e 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  n with the datab
2ecb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2ecc0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2ecd0 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d   .** first argum
2ece0 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ent to be invoke
2ecf0 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
2ed00 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
2ed10 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
2ed20 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
2ed30 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2ed40 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2ed50 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68   function for th
2ed60 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62  e same .** datab
2ed70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2ed80 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2ed90 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
2eda0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2edb0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2edc0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2edd0 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73  hen a .** row is
2ede0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2edf0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a  ed or deleted. .
2ee00 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
2ee10 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
2ee20 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f  lback is.** a co
2ee30 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
2ee40 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2ee50 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2ee60 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
2ee70 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72   callback .** ar
2ee80 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
2ee90 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
2eea0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
2eeb0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  ] or [SQLITE_UPD
2eec0 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  ATE],.** dependi
2eed0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
2eee0 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
2eef0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
2ef00 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54  be invoked..** T
2ef10 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a  he third and .**
2ef20 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2ef30 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
2ef40 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
2ef50 72 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  rs to the databa
2ef60 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65  se and .** table
2ef70 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
2ef80 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
2ef90 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20  w..** The final 
2efa0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
2efb0 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f  er is .** the ro
2efc0 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  wid of the row..
2efd0 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f  ** In the case o
2efe0 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
2eff0 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61  s is the rowid a
2f000 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64  fter .** the upd
2f010 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
2f020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2f030 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
2f040 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
2f050 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
2f060 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
2f070 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
2f080 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
2f090 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a  _sequence)..**.*
2f0a0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  * If another fun
2f0b0 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
2f0c0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
2f0d0 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a   its pArg value.
2f0e0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
2f0f0 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20   Otherwise NULL 
2f100 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2f110 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2f120 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68  *.** {F12971} Th
2f130 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2f140 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
2f150 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2f160 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
2f170 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
2f180 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
2f190 74 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  th first paramet
2f1a0 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  er P whenever.**
2f1b0 20 20 20 20 20 20 20 20 20 20 61 20 74 61 62 6c            a tabl
2f1c0 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65  e row is modifie
2f1d0 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20  d, inserted, or 
2f1e0 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20  deleted on.**   
2f1f0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
2f200 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
2f210 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54  **.** {F12973} T
2f220 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2f230 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
2f240 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f250 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20  s the value.**  
2f260 20 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72          of P for
2f270 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2f280 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ll on the same [
2f290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f2a0 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20  ion] D,.**      
2f2b0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20      or NULL for 
2f2c0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a  the first call..
2f2d0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49  **.** {F12975} I
2f2e0 66 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  f the update hoo
2f2f0 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20  k callback F in 
2f300 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2f310 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20  hook(D,F,P)].** 
2f320 20 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c           is NULL
2f330 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64   then the no upd
2f340 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ate callbacks ar
2f350 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e made..**.** {F
2f360 31 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c  12977} Each call
2f370 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64   to [sqlite3_upd
2f380 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
2f390 20 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72   overrides prior
2f3a0 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
2f3b0 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69     to the same i
2f3c0 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20  nterface on the 
2f3d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2f3e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2f3f0 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65  .** {F12979} The
2f400 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c   update hook cal
2f410 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
2f420 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
2f430 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20  al system.**    
2f440 20 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63        tables suc
2f450 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74  h as sqlite_mast
2f460 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2f470 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66  quence are modif
2f480 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ied..**.** {F129
2f490 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  81} The second p
2f4a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2f4b0 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 20  update callback 
2f4c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2f4d0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2f4e0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
2f4f0 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49  DELETE] or [SQLI
2f500 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20  TE_UPDATE],.**  
2f510 20 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e          dependin
2f520 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2f530 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2f540 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
2f550 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  e invoked..**.**
2f560 20 7b 46 31 32 39 38 33 7d 20 54 68 65 20 74 68   {F12983} The th
2f570 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2f580 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2f590 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2f5a0 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20   pointers.**    
2f5b0 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65        to zero-te
2f5c0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2f5d0 74 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 65  trings which are
2f5e0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
2f5f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
2f600 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
2f610 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 75   that is being u
2f620 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32  pdated...** {F12
2f630 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63  985} The final c
2f640 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2f650 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
2f660 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a  f the row after.
2f670 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f680 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a  change occurs..*
2f690 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2f6a0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
2f6b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2f6c0 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
2f6d0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
2f6e0 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
2f6f0 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
2f700 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
2f710 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72  3REF:  Enable Or
2f720 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
2f730 50 61 67 65 72 20 43 61 63 68 65 20 7b 46 31 30  Pager Cache {F10
2f740 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  330}.**.** This 
2f750 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
2f760 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
2f770 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
2f780 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
2f790 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
2f7a0 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
2f7b0 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  een connections 
2f7c0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
2f7d0 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67  base..** Sharing
2f7e0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2f7f0 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2f800 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64  rue and disabled
2f810 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
2f820 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a  .** is false..**
2f830 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e  .** Cache sharin
2f840 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
2f850 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72   disabled.** for
2f860 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2f870 73 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 69  ss. {END} This i
2f880 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
2f890 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2f8a0 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69  3.5.0..** In pri
2f8b0 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
2f8c0 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77  QLite, sharing w
2f8d0 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72  as.** enabled or
2f8e0 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
2f8f0 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
2f900 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
2f910 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
2f920 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
2f930 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
2f940 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
2f950 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
2f960 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2f970 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2f980 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2f990 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
2f9a0 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
2f9b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
2f9c0 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
2f9d0 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
2f9e0 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
2f9f0 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
2fa00 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a   were opened..**
2fa10 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
2fa20 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
2fa30 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
2fa40 63 61 63 68 65 2e 20 20 20 57 68 65 6e 20 73 68  cache.   When sh
2fa50 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
2fa60 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
2fa70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
2fa80 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64  dule()] API used
2fa90 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
2faa0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77  virtual tables w
2fab0 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
2fac0 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
2fad0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
2fae0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2faf0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2fb00 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65  he was.** enable
2fb10 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75  d or disabled su
2fb20 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2fb30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
2fb40 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
2fb50 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61  rwise..**.** Sha
2fb60 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2fb70 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2fb80 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2fb90 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2fba0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2fbb0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2fbc0 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2fbd0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2fbe0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2fbf0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2fc00 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  licitly..**.** I
2fc10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a  NVARIANTS:.** .*
2fc20 2a 20 7b 46 31 30 33 33 31 7d 20 41 20 73 75 63  * {F10331} A suc
2fc30 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
2fc40 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  on of [sqlite3_e
2fc50 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
2fc60 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20  he(B)].**       
2fc70 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f     will enable o
2fc80 72 20 64 69 73 61 62 6c 65 20 73 68 61 72 65 64  r disable shared
2fc90 20 63 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20   cache mode for 
2fca0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79  any subsequently
2fcb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65  .**          cre
2fcc0 61 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63  ated [database c
2fcd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68  onnection] in th
2fce0 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a  e same process..
2fcf0 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57  **.** {F10336} W
2fd00 68 65 6e 20 73 68 61 72 65 64 20 63 61 63 68 65  hen shared cache
2fd10 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65   is enabled, the
2fd20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2fd30 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20  _module()].**   
2fd40 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2fd50 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
2fd60 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  urn an error..**
2fd70 0a 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 65  .** {F10337} The
2fd80 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
2fd90 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29  _shared_cache(B)
2fda0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2fdb0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2fdc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
2fdd0 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
2fde0 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2fdf0 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  led successfully
2fe00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d  ..**.** {F10339}
2fe10 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
2fe20 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
2fe30 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ault..*/.int sql
2fe40 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
2fe50 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
2fe60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fe70 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2fe80 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31   Heap Memory {F1
2fe90 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7340}.**.** The 
2fea0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2feb0 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
2fec0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a  ce attempts to.*
2fed0 2a 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f  * free N bytes o
2fee0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
2fef0 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
2ff00 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
2ff10 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2ff20 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  s held by the da
2ff30 74 61 62 61 73 65 20 6c 61 62 72 61 72 79 2e 20  tabase labrary. 
2ff40 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73  {END}  Memory us
2ff50 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64  ed.** to cache d
2ff60 61 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f  atabase pages to
2ff70 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
2ff80 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
2ff90 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73  le of.** non-ess
2ffa0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20  ential memory.  
2ffb0 53 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  Sqlite3_release_
2ffc0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2ffd0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2ffe0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
2fff0 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69   freed, which mi
30000 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
30010 65 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ess.** than the 
30020 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
30030 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
30040 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34  TS:.**.** {F1734
30050 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
30060 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
30070 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  )] interface att
30080 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20  empts to.**     
30090 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65       free N byte
300a0 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  s of heap memory
300b0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
300c0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a   non-essential.*
300d0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
300e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65  y allocations he
300f0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
30100 73 65 20 6c 61 62 72 61 72 79 2e 0a 2a 2a 0a 2a  se labrary..**.*
30110 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b  * {F16342} The [
30120 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
30130 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72  memory(N)] retur
30140 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ns the number.**
30150 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 79 74            of byt
30160 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
30170 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  d, which might b
30180 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a  e more or less.*
30190 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
301a0 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
301b0 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sted..*/.int sql
301c0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
301d0 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
301e0 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f   CAPI3REF:  Impo
301f0 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
30200 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d  ap Size {F17350}
30210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30220 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
30230 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  it() interface.*
30240 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  * places a "soft
30250 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61  " limit on the a
30260 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
30270 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
30280 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79   allocated.** by
30290 20 53 51 4c 69 74 65 2e 20 49 66 20 61 6e 20 69   SQLite. If an i
302a0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
302b0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
302c0 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65  .** that would e
302d0 78 63 65 65 64 20 74 68 65 20 73 6f 66 74 20 68  xceed the soft h
302e0 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
302f0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
30300 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f  ry()] is.** invo
30310 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ked one or more 
30320 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
30330 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
30340 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
30350 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a  n.** is made..**
30360 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73  .** The limit is
30370 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20   called "soft", 
30380 62 65 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73  because if.** [s
30390 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
303a0 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a  emory()] cannot.
303b0 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ** free sufficie
303c0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
303d0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
303e0 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
303f0 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
30400 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
30410 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
30420 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
30430 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
30440 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65  A negative or ze
30450 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d  ro value for N m
30460 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20  eans that there 
30470 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20  is no soft heap 
30480 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71  limit and.** [sq
30490 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
304a0 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c  mory()] will onl
304b0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
304c0 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75   memory is exhau
304d0 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66  sted..** The def
304e0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
304f0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
30500 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
30510 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  * SQLite makes a
30520 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20   best effort to 
30530 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68  honor the soft h
30540 65 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20  eap limit.  .** 
30550 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
30560 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
30570 74 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75  t honored, execu
30580 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
30590 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
305a0 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
305b0 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68  ion.  This is wh
305c0 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a  y the limit is .
305d0 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66  ** called a "sof
305e0 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73  t" limit.  It is
305f0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
30600 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
30610 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
30620 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  5.0, this routin
30630 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e  e only constrain
30640 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ed the memory.**
30650 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20   allocated by a 
30660 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20  single thread - 
30670 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30680 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f  in which this ro
30690 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20  utine.** runs.  
306a0 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53  Beginning with S
306b0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
306c0 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65  5.0, the soft he
306d0 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61  ap limit is.** a
306e0 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68  pplied to all th
306f0 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65  reads. The value
30700 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74   specified for t
30710 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
30720 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65  it.** is an uppe
30730 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74  r bound on the t
30740 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  otal memory allo
30750 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74  cation for all t
30760 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65  hreads. In.** ve
30770 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72  rsion 3.5.0 ther
30780 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73  e is no mechanis
30790 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74  m for limiting t
307a0 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f  he heap usage fo
307b0 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20  r.** individual 
307c0 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49  threads..**.** I
307d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
307e0 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73   {F16351} The [s
307f0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
30800 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72  _limit(N)] inter
30810 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f  face places a so
30820 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20  ft limit.**     
30830 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20       of N bytes 
30840 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
30850 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
30860 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
30870 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  ed.**          u
30880 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
30890 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
308a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61  te3_realloc()] a
308b0 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20  t any point.**  
308c0 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e          in time.
308d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20  .**.** {F16352} 
308e0 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
308f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
30900 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
30910 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20  loc()] would.** 
30920 20 20 20 20 20 20 20 20 20 63 61 75 73 65 20 74           cause t
30930 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20  he total amount 
30940 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d  of allocated mem
30950 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20 74 68  ory to exceed th
30960 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f  e.**          so
30970 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74  ft heap limit, t
30980 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  hen [sqlite3_rel
30990 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
309a0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
309b0 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65        in an atte
309c0 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 74 68  mpt to reduce th
309d0 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70  e memory usage p
309e0 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69  rior to proceedi
309f0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ng.**          w
30a00 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ith the memory a
30a10 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70  llocation attemp
30a20 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33  t..**.** {F16353
30a30 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
30a40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
30a50 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
30a60 63 28 29 5d 20 74 68 61 74 20 74 72 69 67 67 65  c()] that trigge
30a70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  r.**          at
30a80 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65  tempts to reduce
30a90 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68   memory usage th
30aa0 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74 20 68  rough the soft h
30ab0 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20  eap limit.**    
30ac0 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20        mechanism 
30ad0 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66  continue even if
30ae0 20 74 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20   the attempt to 
30af0 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a  reduce memory.**
30b00 20 20 20 20 20 20 20 20 20 20 75 73 61 67 65 20            usage 
30b10 69 73 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e  is unsuccessful.
30b20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20  .**.** {F16354} 
30b30 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65  A negative or ze
30b40 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69  ro value for N i
30b50 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20  n a call to.**  
30b60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
30b70 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
30b80 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  (N)] means that 
30b90 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
30ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 65 61  .**          hea
30bb0 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c  p limit and [sql
30bc0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
30bd0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
30be0 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
30bf0 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
30c00 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79  ry is completely
30c10 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a   exhausted..**.*
30c20 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64  * {F16355} The d
30c30 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
30c40 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
30c50 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
30c60 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63  .** {F16358} Eac
30c70 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
30c80 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
30c90 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73  it(N)] overrides
30ca0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30cb0 20 76 61 6c 75 65 73 20 73 65 74 20 62 79 20 61   values set by a
30cc0 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  ll prior calls..
30cd0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
30ce0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
30cf0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
30d00 49 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 20  I3REF:  Extract 
30d10 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
30d20 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
30d30 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a  le {F12850}.**.*
30d40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  * This routine.*
30d50 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64  * returns meta-d
30d60 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
30d70 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
30d80 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
30d90 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65  se.** table acce
30da0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
30db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   connection hand
30dc0 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  le passed as the
30dd0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
30de0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  .** argument..**
30df0 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69  .** The column i
30e00 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
30e10 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
30e20 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
30e30 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74  ameters to .** t
30e40 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
30e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
30e60 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
30e70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
30e80 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
30e90 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72  main", "temp" or
30ea0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
30eb0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
30ec0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
30ed0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
30ee0 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
30ef0 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
30f00 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
30f10 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
30f20 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
30f30 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
30f40 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62  thm as the datab
30f50 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20  ase engine uses 
30f60 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75  to .** resolve u
30f70 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
30f80 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
30f90 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
30fa0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
30fb0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
30fc0 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
30fd0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a  e and column .**
30fe0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
30ff0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
31000 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
31010 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
31020 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62  meters .** may b
31030 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65  e NULL..**.** Me
31040 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ta information i
31050 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
31060 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
31070 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
31080 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35  ssed as.** the 5
31090 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  th and subsequen
310a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
310b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41  this function. A
310c0 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20  ny of these .** 
310d0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
310e0 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
310f0 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
31100 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
31110 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72  f meta .** infor
31120 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 6d 69 74 74  mation is ommitt
31130 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ed..**.** <pre>.
31140 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20  ** Parameter    
31150 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20   Output Type    
31160 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
31170 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
31180 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
31190 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68  ----.**.**   5th
311a0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63           const c
311b0 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74  har*      Data t
311c0 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20  ype.**   6th    
311d0 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a       const char*
311e0 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68        Name of th
311f0 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  e default collat
31200 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a  ion sequence .**
31210 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69     7th         i
31220 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
31230 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
31240 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
31250 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
31260 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e    8th         in
31270 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
31280 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
31290 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
312a0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
312b0 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e    9th         in
312c0 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
312d0 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
312e0 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45  n is AUTOINCREME
312f0 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a  NT.** </pre>.**.
31300 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79  **.** The memory
31310 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
31320 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
31330 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
31340 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61  or the .** decla
31350 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
31360 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31370 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
31380 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
31390 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20  .** call to any 
313a0 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74  sqlite API funct
313b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
313c0 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
313d0 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
313e0 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72  view, then an er
313f0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
31400 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
31410 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
31420 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
31430 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
31440 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52  d an .** INTEGER
31450 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
31460 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
31470 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
31480 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
31490 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  t .** parameters
314a0 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
314b0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
314c0 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20  ared column. If 
314d0 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
314e0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
314f0 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74  ed IPK column, t
31500 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70  hen the output p
31510 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
31520 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73  t as .** follows
31530 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
31540 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
31550 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
31560 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
31570 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
31580 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
31590 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
315a0 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
315b0 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
315c0 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20  ** </pre>.**.** 
315d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
315e0 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
315f0 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
31600 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
31610 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
31620 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
31630 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
31640 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
31650 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
31660 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
31670 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72  d, an SQLITE err
31680 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
31690 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
316a0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74   message.** left
316b0 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
316c0 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72   handle (to be r
316d0 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
316e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
316f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
31700 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
31710 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
31720 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
31730 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
31740 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
31750 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
31760 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
31770 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
31780 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
31790 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
317a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
317b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
317c0 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
317d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
317e0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
317f0 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
31800 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
31810 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
31820 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
31830 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
31840 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
31850 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
31860 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
31870 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
31880 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
31890 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
318a0 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
318b0 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
318c0 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
318d0 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
318e0 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
318f0 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
31900 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
31910 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
31920 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
31930 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
31940 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
31950 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
31960 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
31970 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
31980 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
31990 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
319a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
319b0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
319c0 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
319d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
319e0 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
319f0 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a  nsion {F12600}.*
31a00 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68  *.** {F12601} Th
31a10 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
31a20 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
31a30 66 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73  face.** attempts
31a40 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69   to load an SQLi
31a50 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
31a60 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
31a70 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46  n the file.** zF
31a80 69 6c 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68  ile. {F12602} Th
31a90 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
31aa0 20 7a 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d   zProc. {F12603}
31ab0 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a   zProc may be 0.
31ac0 2a 2a 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  ** in which case
31ad0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31ae0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66   entry point def
31af0 61 75 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c  aults.** to "sql
31b00 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
31b10 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  nit"..**.** {F12
31b20 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33  604} The sqlite3
31b30 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
31b40 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ) interface shal
31b50 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
31b60 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
31b70 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
31b80 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
31b90 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
31ba0 2a 0a 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a  *.** {F12605}.**
31bb0 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
31bc0 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67  urs and pzErrMsg
31bd0 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20   is not 0, then 
31be0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  the.** sqlite3_l
31bf0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
31c00 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
31c10 61 74 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20  attempt to fill 
31c20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a  *pzErrMsg with .
31c30 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ** error message
31c40 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20   text stored in 
31c50 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
31c60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
31c70 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44  lloc()]..** {END
31c80 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  }  The calling f
31c90 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66  unction should f
31ca0 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a  ree this memory.
31cb0 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ** by calling [s
31cc0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
31cd0 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a  **.** {F12606}.*
31ce0 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * Extension load
31cf0 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
31d00 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
31d10 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
31d20 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70  xtension()].** p
31d30 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
31d40 74 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65  this API or an e
31d50 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
31d60 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  urned..*/.int sq
31d70 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
31d80 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
31d90 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
31da0 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
31db0 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
31dc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31dd0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
31de0 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
31df0 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
31e00 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
31e10 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
31e20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
31e30 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
31e40 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
31e50 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
31e60 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
31e70 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
31e80 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
31e90 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
31ea0 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
31eb0 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65  API3REF:  Enable
31ec0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
31ed0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46  nsion Loading {F
31ee0 31 32 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20  12620}.**.** So 
31ef0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
31f00 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
31f10 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
31f20 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
31f30 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
31f40 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
31f50 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
31f60 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
31f70 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
31f80 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
31f90 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
31fa0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
31fb0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
31fc0 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20  API is provided 
31fd0 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
31fe0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
31ff0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
32000 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20   on and.** off. 
32010 20 7b 46 31 32 36 32 32 7d 20 49 74 20 69 73 20   {F12622} It is 
32020 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
32030 7b 45 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74  {END} See ticket
32040 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46   #1863..**.** {F
32050 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20  12621} Call the 
32060 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
32070 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
32080 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20  routine.** with 
32090 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e  onoff==1 to turn
320a0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
320b0 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c  ng on.** and cal
320c0 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
320d0 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61  =0 to turn it ba
320e0 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45  ck off again. {E
320f0 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ND}.*/.int sqlit
32100 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
32110 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
32120 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
32130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32140 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d  F: Make Arrangem
32150 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69  ents To Automati
32160 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78  cally Load An Ex
32170 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d  tension {F12640}
32180 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20  .**.** {F12641} 
32190 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  This function.**
321a0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78   registers an ex
321b0 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
321c0 69 6e 74 20 74 68 61 74 20 69 73 20 61 75 74 6f  int that is auto
321d0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
321e0 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20  d.** whenever a 
321f0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
32200 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
32210 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
32220 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
32230 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
32240 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
32250 6e 5f 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a  n_v2()]. {END}.*
32260 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61  *.** This API ca
32270 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20  n be invoked at 
32280 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20  program startup 
32290 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69  in order to regi
322a0 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  ster.** one or m
322b0 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c  ore statically l
322c0 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73  inked extensions
322d0 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76   that will be av
322e0 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c  ailable.** to al
322f0 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  l new database c
32300 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  onnections..**.*
32310 2a 20 7b 46 31 32 36 34 32 7d 20 44 75 70 6c 69  * {F12642} Dupli
32320 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
32330 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
32340 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
32350 74 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  tine multiple.**
32360 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
32370 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69  same extension i
32380 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a  s harmless..**.*
32390 2a 20 7b 46 31 32 36 34 33 7d 20 54 68 69 73 20  * {F12643} This 
323a0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
323b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
323c0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20  extension in an 
323d0 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69 73  array.** that is
323e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
323f0 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e 20  qlite_malloc(). 
32400 7b 45 4e 44 7d 20 49 66 20 79 6f 75 20 72 75 6e  {END} If you run
32410 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a 2a   a memory leak.*
32420 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f 75  * checker on you
32430 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69 74  r program and it
32440 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b 20   reports a leak 
32450 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  because of this.
32460 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20 69  ** array, then i
32470 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72  nvoke [sqlite3_r
32480 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
32490 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a 20  ion()] prior.** 
324a0 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20 66  to shutdown to f
324b0 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a  ree the memory..
324c0 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 34 7d 20 41  **.** {F12644} A
324d0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
324e0 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73  ons apply across
324f0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45   all threads. {E
32500 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ND}.**.** This i
32510 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65  nterface is expe
32520 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
32530 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
32540 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c 20  e or.** removal 
32550 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
32560 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
32570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74  .int sqlite3_aut
32580 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64  o_extension(void
32590 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b 0a   *xEntryPoint);.
325a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
325b0 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
325c0 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
325d0 69 6e 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a 0a  ing {F12660}.**.
325e0 2a 2a 20 7b 46 31 32 36 36 31 7d 20 54 68 69 73  ** {F12661} This
325f0 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
32600 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c  es all previousl
32610 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  y registered.** 
32620 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  automatic extens
32630 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 54 68 69  ions. {END}  Thi
32640 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  s.** routine und
32650 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
32660 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71 6c  f all prior [sql
32670 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
32680 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e  ion()].** calls.
32690 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 32 7d 20  .**.** {F12662} 
326a0 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62 6c  This call disabl
326b0 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ed automatic ext
326c0 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74  ensions in all t
326d0 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a  hreads. {END}.**
326e0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
326f0 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ce is experiment
32700 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
32710 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a  t to change or.*
32720 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  * removal in fut
32730 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
32740 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
32750 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
32760 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
32770 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20  d);.../*.****** 
32780 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
32790 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
327a0 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
327b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
327c0 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
327d0 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
327e0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
327f0 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  m is currently c
32800 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
32810 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
32820 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
32830 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
32840 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
32850 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
32860 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
32870 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
32880 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
32890 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
328a0 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
328b0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
328c0 6d 20 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20  m stablizes, we 
328d0 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
328e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
328f0 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
32900 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
32910 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
32920 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  mment..*/../*.**
32930 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64   Structures used
32940 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20   by the virtual 
32950 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a  table interface.
32960 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
32970 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  t sqlite3_vtab s
32980 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70  qlite3_vtab;.typ
32990 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
329a0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
329b0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
329c0 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  o;.typedef struc
329d0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
329e0 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74  ursor sqlite3_vt
329f0 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64  ab_cursor;.typed
32a00 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
32a10 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33  3_module sqlite3
32a20 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20  _module;../*.** 
32a30 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
32a40 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20 7b  l Table Object {
32a50 46 31 38 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f  F18000}.** KEYWO
32a60 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
32a70 75 6c 65 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f 64 75  ule.**.** A modu
32a80 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f 66  le is a class of
32a90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
32aa0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 73    Each module is
32ab0 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 61   defined.** by a
32ac0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
32ad0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
32ae0 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74 72  cture.  This str
32af0 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 0a  ucture consists.
32b00 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ** mostly of met
32b10 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
32b20 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ule..*/.struct s
32b30 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
32b40 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
32b50 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
32b60 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
32b70 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
32b80 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
32b90 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
32ba0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
32bb0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
32bc0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
32bd0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
32be0 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
32bf0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
32c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
32c10 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
32c20 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
32c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
32c40 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
32c50 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
32c60 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
32c70 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
32c80 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
32c90 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
32ca0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
32cb0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
32cc0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
32cd0 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
32ce0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
32cf0 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
32d00 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
32d10 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
32d20 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
32d30 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
32d40 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
32d50 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
32d60 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
32d70 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
32d80 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
32d90 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
32da0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
32db0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
32dc0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
32dd0 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
32de0 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
32df0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
32e00 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
32e10 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
32e20 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
32e30 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
32e40 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
32e50 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
32e60 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
32e70 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
32e80 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
32e90 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
32ea0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
32eb0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
32ec0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
32ed0 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
32ee0 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
32ef0 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
32f00 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
32f10 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
32f20 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
32f30 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
32f40 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
32f50 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
32f60 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
32f70 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
32f80 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
32f90 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
32fa0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
32fb0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
32fc0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
32fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32fe0 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
32ff0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33000 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33010 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
33020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33030 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 0a  void **ppArg);..
33040 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
33050 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
33060 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
33070 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
33080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
33090 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
330a0 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  ing Information 
330b0 7b 46 31 38 31 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F18100}.** KEYW
330c0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e  ORDS: sqlite3_in
330d0 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54  dex_info.**.** T
330e0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
330f0 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
33100 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
33110 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74 6f  tures is used to
33120 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
33130 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
33140 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
33150 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74 49 6e  from the xBestIn
33160 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  dex.** method of
33170 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75   an sqlite3_modu
33180 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  le.  The fields 
33190 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
331a0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
331b0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
331c0 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
331d0 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
331e0 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
331f0 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
33200 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
33210 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 43  ds..**.** The aC
33220 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
33230 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
33240 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
33250 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ts of the.** for
33260 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20 20 20  m:.**.**        
33270 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 0a   column OP expr.
33280 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50 20 69  **.** Where OP i
33290 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
332a0 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
332b0 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72 74 69  .  .** The parti
332c0 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
332d0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
332e0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
332f0 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74    The index of t
33300 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
33310 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f 6e 73  red in .** aCons
33320 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e  traint[].iColumn
33330 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  .  aConstraint[]
33340 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
33350 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
33360 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
33370 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
33380 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
33390 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
333a0 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
333b0 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
333c0 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nnot..**.** The 
333d0 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61  optimizer automa
333e0 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20  tically inverts 
333f0 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72  terms of the for
33400 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d  m "expr OP colum
33410 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20  n".** and makes 
33420 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61  other simplifica
33430 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45  tions to the WHE
33440 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20  RE clause in an 
33450 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65  attempt to.** ge
33460 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20  t as many WHERE 
33470 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74  clause terms int
33480 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e  o the form shown
33490 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62   above as possib
334a0 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f 6e 73  le..** The aCons
334b0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
334c0 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
334d0 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
334e0 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a 2a 2a  n the correct.**
334f0 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66 65 72   form that refer
33500 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
33510 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
33520 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
33530 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74 69 6f  **.** Informatio
33540 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
33550 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
33560 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
33570 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74 65 72  y[]..** Each ter
33580 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
33590 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
335a0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
335b0 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
335c0 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68   xBestIndex meth
335d0 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
335e0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
335f0 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
33600 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
33610 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
33620 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49  s to xFilter.  I
33630 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
33640 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
33650 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
33660 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
33670 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
33680 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
33690 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
336a0 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
336b0 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f  in argv.  If aCo
336c0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
336d0 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
336e0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
336f0 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
33700 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
33710 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
33720 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
33730 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
33740 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a  gain by SQLite..
33750 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d  **.** The idxNum
33760 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75   and idxPtr valu
33770 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20  es are recorded 
33780 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20  and passed into 
33790 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71 6c 69  xFilter..** sqli
337a0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 75 73  te3_free() is us
337b0 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
337c0 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65 65 49  r if needToFreeI
337d0 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
337e0 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
337f0 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
33800 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
33810 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f 63 63  xFilter will occ
33820 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
33830 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
33840 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
33850 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
33860 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
33870 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
33880 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
33890 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
338a0 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
338b0 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
338c0 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
338d0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
338e0 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
338f0 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
33900 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
33910 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
33920 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
33930 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
33940 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
33950 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
33960 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
33970 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
33980 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
33990 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
339a0 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
339b0 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
339c0 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
339d0 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
339e0 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
339f0 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
33a00 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
33a10 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
33a20 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
33a30 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
33a40 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
33a50 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
33a60 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
33a70 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
33a80 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
33a90 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
33aa0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
33ab0 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
33ac0 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
33ad0 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
33ae0 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
33af0 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
33b00 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
33b10 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
33b20 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
33b30 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
33b40 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
33b50 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
33b60 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
33b70 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
33b80 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
33b90 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
33ba0 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
33bb0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
33bc0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
33bd0 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
33be0 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
33bf0 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
33c00 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
33c10 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
33c20 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
33c30 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
33c40 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
33c50 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
33c60 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
33c70 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
33c80 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
33c90 2f 0a 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20  /..  /* Outputs 
33ca0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
33cb0 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
33cc0 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20  aint_usage {.   
33cd0 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
33ce0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
33cf0 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
33d00 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
33d10 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20  o xFilter */.   
33d20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
33d30 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20  mit;      /* Do 
33d40 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20  not code a test 
33d50 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61  for this constra
33d60 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  int */.  } *aCon
33d70 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20  straintUsage;.  
33d80 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20  int idxNum;     
33d90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
33da0 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65  mber used to ide
33db0 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20  ntify the index 
33dc0 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74  */.  char *idxSt
33dd0 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  r;              
33de0 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
33df0 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
33e00 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
33e10 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f   */.  int needTo
33e20 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20  FreeIdxStr;     
33e30 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20   /* Free idxStr 
33e40 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  using sqlite3_fr
33e50 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a  ee() if true */.
33e60 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e    int orderByCon
33e70 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20  sumed;       /* 
33e80 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69  True if output i
33e90 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65  s already ordere
33ea0 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73  d */.  double es
33eb0 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20  timatedCost;    
33ec0 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63    /* Estimated c
33ed0 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ost of using thi
33ee0 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64  s index */.};.#d
33ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
33f00 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51  EX_CONSTRAINT_EQ
33f10 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
33f20 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
33f30 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64  RAINT_GT    4.#d
33f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
33f50 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45  EX_CONSTRAINT_LE
33f60 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
33f70 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
33f80 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23  RAINT_LT    16.#
33f90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
33fa0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
33fb0 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20  E    32.#define 
33fc0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
33fd0 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34  STRAINT_MATCH 64
33fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33ff0 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72  : Register A Vir
34000 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65  tual Table Imple
34010 6d 65 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 30  mentation {F1820
34020 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
34030 75 74 69 6e 65 20 69 73 20 75 73 65 64 20 74 6f  utine is used to
34040 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
34050 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 77 69 74 68  module name with
34060 20 61 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f   an SQLite.** co
34070 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d 6f 64 75 6c  nnection.  Modul
34080 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
34090 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
340a0 65 20 63 72 65 61 74 69 6e 67 20 6e 65 77 0a 2a  e creating new.*
340b0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
340c0 20 6f 6e 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20   on the module, 
340d0 6f 72 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  or before using 
340e0 70 72 65 65 78 69 73 74 69 6e 67 20 76 69 72 74  preexisting virt
340f0 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 73 20 6f 66  ual.** tables of
34100 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a   the module..*/.
34110 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34120 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
34130 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
34140 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
34150 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
34160 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
34170 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
34180 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
34190 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
341a0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
341b0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
341c0 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
341d0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
341e0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
341f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34200 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
34210 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
34220 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 0a  xConnect */.);..
34230 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34240 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
34250 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
34260 6e 74 61 74 69 6f 6e 20 7b 46 31 38 32 31 30 7d  ntation {F18210}
34270 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34280 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ine is identical
34290 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
342a0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 20  create_module() 
342b0 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c 0a 2a 2a  method above,.**
342c0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
342d0 61 6c 6c 6f 77 73 20 61 20 64 65 73 74 72 75 63  allows a destruc
342e0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  tor function to 
342f0 62 65 20 73 70 65 63 69 66 69 65 64 2e 20 49 74  be specified. It
34300 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d 6f 72 65   is.** even more
34310 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 74 68   experimental th
34320 61 6e 20 74 68 65 20 72 65 73 74 20 6f 66 20 74  an the rest of t
34330 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
34340 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74 20 73 71  s API..*/.int sq
34350 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
34360 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ule_v2(.  sqlite
34370 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34380 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
34390 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
343a0 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
343b0 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
343c0 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
343d0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
343e0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
343f0 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
34400 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65 74 68 6f  e *,    /* Metho
34410 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
34420 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  e */.  void *,  
34430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34440 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
34450 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
34460 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28  nnect */.  void(
34470 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
34480 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20  )     /* Module 
34490 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
344a0 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ion */.);../*.**
344b0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
344c0 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63  al Table Instanc
344d0 65 20 4f 62 6a 65 63 74 20 7b 46 31 38 30 31 30  e Object {F18010
344e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  }.** KEYWORDS: s
344f0 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a  qlite3_vtab.**.*
34500 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20 69  * Every module i
34510 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
34520 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  es a subclass of
34530 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
34540 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20 64  tructure.** to d
34550 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
34560 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66  ular instance of
34570 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
34580 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
34590 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
345a0 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
345b0 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
345c0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
345d0 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70 75 72  on.   The.** pur
345e0 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70  pose of this sup
345f0 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65  erclass is to de
34600 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65  fine certain fie
34610 6c 64 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  lds that are com
34620 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6d 6f  mon.** to all mo
34630 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
34640 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ions..**.** Virt
34650 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f  ual tables metho
34660 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72  ds can set an er
34670 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61  ror message by a
34680 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74  ssigning a.** st
34690 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
346a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
346b0 74 66 28 29 20 74 6f 20 7a 45 72 72 4d 73 67 2e  tf() to zErrMsg.
346c0 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
346d0 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
346e0 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
346f0 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
34700 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  by a call to sql
34710 69 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a 20 70  ite3_free().** p
34720 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
34730 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
34740 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66 74 65  o zErrMsg.  Afte
34750 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34760 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
34770 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
34780 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
34790 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
347a0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
347b0 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
347c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
347d0 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
347e0 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
347f0 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74 68 61  ed.  Note.** tha
34800 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  t sqlite3_mprint
34810 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
34820 66 72 65 65 28 29 20 61 72 65 20 75 73 65 64 20  free() are used 
34830 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66  on the zErrMsg f
34840 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20 76 69  ield.** since vi
34850 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61 72 65  rtual tables are
34860 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c 65 6d   commonly implem
34870 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61 62 6c  ented in loadabl
34880 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77 68 69  e extensions whi
34890 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68 61 76  ch.** do not hav
348a0 65 20 61 63 63 65 73 73 20 74 6f 20 73 71 6c 69  e access to sqli
348b0 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f 72 20  te3MPrintf() or 
348c0 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e 0a 2a  sqlite3Free()..*
348d0 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
348e0 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20  _vtab {.  const 
348f0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
34900 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65  pModule;  /* The
34910 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73   module for this
34920 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a   virtual table *
34930 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20  /.  int nRef;   
34940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34950 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
34960 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68 61 72  rnally */.  char
34970 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
34980 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
34990 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
349a0 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
349b0 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
349c0 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
349d0 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
349e0 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
349f0 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
34a00 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
34a10 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
34a20 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
34a30 74 20 20 7b 46 31 38 30 32 30 7d 0a 2a 2a 20 4b  t  {F18020}.** K
34a40 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
34a50 5f 76 74 61 62 5f 63 75 72 73 6f 72 0a 2a 2a 0a  _vtab_cursor.**.
34a60 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65 20  ** Every module 
34a70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
34a80 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
34a90 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
34aa0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f 20  structure.** to 
34ab0 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
34ac0 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
34ad0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
34ae0 6c 65 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a  le and are used.
34af0 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75  ** to loop throu
34b00 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  gh the virtual t
34b10 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61  able.  Cursors a
34b20 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
34b30 20 74 68 65 0a 2a 2a 20 78 4f 70 65 6e 20 6d 65   the.** xOpen me
34b40 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75  thod of the modu
34b50 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  le.  Each module
34b60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34b70 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74  will define.** t
34b80 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20  he content of a 
34b90 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65  cursor structure
34ba0 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e   to suit its own
34bb0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
34bc0 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78  is superclass ex
34bd0 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ists in order to
34be0 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f   define fields o
34bf0 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61  f the cursor tha
34c00 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20  t.** are common 
34c10 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  to all implement
34c20 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63  ations..*/.struc
34c30 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
34c40 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65  ursor {.  sqlite
34c50 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20  3_vtab *pVtab;  
34c60 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74      /* Virtual t
34c70 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72  able of this cur
34c80 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  sor */.  /* Virt
34c90 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
34ca0 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
34cb0 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
34cc0 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
34cd0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
34ce0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68  3REF: Declare Th
34cf0 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69  e Schema Of A Vi
34d00 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 46 31 38  rtual Table {F18
34d10 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  280}.**.** The x
34d20 43 72 65 61 74 65 20 61 6e 64 20 78 43 6f 6e 6e  Create and xConn
34d30 65 63 74 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ect methods of a
34d40 20 6d 6f 64 75 6c 65 20 75 73 65 20 74 68 65 20   module use the 
34d50 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
34d60 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20   to declare the 
34d70 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65  format (the name
34d80 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20  s and datatypes 
34d90 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20  of the columns) 
34da0 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61  of.** the virtua
34db0 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d  l tables they im
34dc0 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20  plement..*/.int 
34dd0 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f  sqlite3_declare_
34de0 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63  vtab(sqlite3*, c
34df0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72 65 61  onst char *zCrea
34e00 74 65 54 61 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a  teTable);../*.**
34e10 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c   CAPI3REF: Overl
34e20 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46  oad A Function F
34e30 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  or A Virtual Tab
34e40 6c 65 20 7b 46 31 38 33 30 30 7d 0a 2a 2a 0a 2a  le {F18300}.**.*
34e50 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
34e60 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
34e70 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
34e80 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
34e90 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
34ea0 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  he xFindFunction
34eb0 20 6d 65 74 68 6f 64 2e 20 20 42 75 74 20 67 6c   method.  But gl
34ec0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
34ed0 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
34ee0 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
34ef0 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
34f00 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
34f10 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73  This API makes s
34f20 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72  ure a global ver
34f30 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69  sion of a functi
34f40 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63  on with a partic
34f50 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64  ular.** name and
34f60 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
34f70 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49  eters exists.  I
34f80 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69  f no such functi
34f90 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66  on exists.** bef
34fa0 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20  ore this API is 
34fb0 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75  called, a new fu
34fc0 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  nction is create
34fd0 64 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  d.  The implemen
34fe0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
34ff0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
35000 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
35010 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
35020 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
35030 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
35040 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
35050 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
35060 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
35070 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
35080 20 61 20 70 6c 61 63 65 2d 68 6f 6c 64 65 72 20   a place-holder 
35090 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
350a0 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a  n be overloaded.
350b0 2a 2a 20 62 79 20 76 69 72 74 75 61 6c 20 74 61  ** by virtual ta
350c0 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bles..**.** This
350d0 20 41 50 49 20 73 68 6f 75 6c 64 20 62 65 20 63   API should be c
350e0 6f 6e 73 69 64 65 72 65 64 20 70 61 72 74 20 6f  onsidered part o
350f0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
35100 62 6c 65 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  ble interface,.*
35110 2a 20 77 68 69 63 68 20 69 73 20 65 78 70 65 72  * which is exper
35120 69 6d 65 6e 74 61 6c 20 61 6e 64 20 73 75 62 6a  imental and subj
35130 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
35140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  /.int sqlite3_ov
35150 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
35160 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
35170 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
35180 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
35190 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
351a0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
351b0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
351c0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
351d0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
351e0 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
351f0 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
35200 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
35210 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
35220 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
35230 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
35240 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
35250 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
35260 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
35270 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
35280 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
35290 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
352a0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
352b0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
352c0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
352d0 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
352e0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
352f0 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
35300 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
35310 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
35320 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
35330 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a  his comment..**.
35340 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ****** EXPERIMEN
35350 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f  TAL - subject to
35360 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20   change without 
35370 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  notice *********
35380 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *****.*/../*.** 
35390 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
353a0 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
353b0 4f 42 20 7b 46 31 37 38 30 30 7d 0a 2a 2a 0a 2a  OB {F17800}.**.*
353c0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
353d0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
353e0 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
353f0 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a  BLOB on which.**
35400 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   incremental I/O
35410 20 63 61 6e 20 62 65 20 70 72 65 66 6f 72 6d 65   can be preforme
35420 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74 73 20 6f 66  d..** Objects of
35430 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63   this type are c
35440 72 65 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71  reated by.** [sq
35450 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
35460 29 5d 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  )] and destroyed
35470 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
35480 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54  b_close()]..** T
35490 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
354a0 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
354b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
354c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
354d0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
354e0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
354f0 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
35500 20 6f 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a   of the blob..**
35510 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   The [sqlite3_bl
35520 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
35530 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
35540 65 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  e size of the.**
35550 20 62 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a   blob in bytes..
35560 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
35570 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73  t sqlite3_blob s
35580 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a  qlite3_blob;../*
35590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
355a0 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e  en A BLOB For In
355b0 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 46  cremental I/O {F
355c0 31 37 38 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  17810}.**.** Thi
355d0 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65  s interfaces ope
355e0 6e 73 20 61 20 68 61 6e 64 6c 65 20 74 6f 20 74  ns a handle to t
355f0 68 65 20 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a  he blob located.
35600 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c  ** in row iRow,,
35610 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c   column zColumn,
35620 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e   table zTable in
35630 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a   database zDb;.*
35640 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * in other words
35650 2c 20 20 74 68 65 20 73 61 6d 65 20 62 6c 6f 62  ,  the same blob
35660 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73   that would be s
35670 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  elected by:.**.*
35680 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53  * <pre>.**     S
35690 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52  ELECT zColumn FR
356a0 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48  OM zDb.zTable WH
356b0 45 52 45 20 72 6f 77 69 64 20 3d 20 69 52 6f 77  ERE rowid = iRow
356c0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44  ;.** </pre> {END
356d0 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  }.**.** If the f
356e0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
356f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
35700 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20 66  blob is opened f
35710 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61 6e 64 20  or .** read and 
35720 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 49 66  write access. If
35730 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65   it is zero, the
35740 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65 64 20   blob is opened 
35750 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20 61 63 63  for read .** acc
35760 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75  ess..**.** On su
35770 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
35780 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  K] is returned a
35790 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a 2a 20 5b  nd the new .** [
357a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
357b0 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  lob handle] is w
357c0 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f  ritten to *ppBlo
357d0 62 2e 20 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  b. .** Otherwise
357e0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
357f0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a  s returned and .
35800 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69  ** any value wri
35810 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20  tten to *ppBlob 
35820 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
35830 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ed by the caller
35840 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  ..** This functi
35850 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61 74 61  on sets the data
35860 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72 72 6f  base-handle erro
35870 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
35880 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
35890 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
358a0 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
358b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
358c0 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  .** .** INVARIAN
358d0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31  TS:.**.** {F1781
358e0 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
358f0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
35900 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
35910 6f 70 65 6e 28 44 2c 42 2c 54 2c 43 2c 52 2c 46  open(D,B,T,C,R,F
35920 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,P)].**         
35930 20 69 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73   interface opens
35940 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   an [sqlite3_blo
35950 62 5d 20 6f 62 6a 65 63 74 20 50 20 6f 6e 20 74  b] object P on t
35960 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20 20  he blob.**      
35970 20 20 20 20 69 6e 20 63 6f 6c 75 6d 6e 20 43 20      in column C 
35980 6f 66 20 74 61 62 6c 65 20 54 20 69 6e 20 64 61  of table T in da
35990 74 61 62 61 73 65 20 42 20 6f 6e 20 5b 64 61 74  tabase B on [dat
359a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
359b0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  ] D..**.** {F178
359c0 31 34 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  14} A successful
359d0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
359e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
359f0 6e 28 44 2c 2e 2e 2e 29 5d 20 73 74 61 72 74 73  n(D,...)] starts
35a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e  .**          a n
35a10 65 77 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f  ew transaction o
35a20 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
35a30 65 63 74 69 6f 6e 5d 20 44 20 69 66 20 74 68 61  ection] D if tha
35a40 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  t connection.** 
35a50 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20           is not 
35a60 61 6c 72 65 61 64 79 20 69 6e 20 61 20 74 72 61  already in a tra
35a70 6e 73 61 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nsaction..**.** 
35a80 7b 46 31 37 38 31 36 7d 20 54 68 65 20 5b 73 71  {F17816} The [sq
35a90 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
35aa0 44 2c 42 2c 54 2c 43 2c 52 2c 46 2c 50 29 5d 20  D,B,T,C,R,F,P)] 
35ab0 69 6e 74 65 72 66 61 63 65 20 6f 70 65 6e 73 20  interface opens 
35ac0 74 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20 20 20  the blob.**     
35ad0 20 20 20 20 20 66 6f 72 20 72 65 61 64 20 61 6e       for read an
35ae0 64 20 77 72 69 74 65 20 61 63 63 65 73 73 20 69  d write access i
35af0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
35b00 65 20 46 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  e F parameter.**
35b10 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
35b20 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  -zero..**.** {F1
35b30 37 38 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  7819} The [sqlit
35b40 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
35b50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35b60 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
35b70 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75   .**          su
35b80 63 63 65 73 73 20 61 6e 64 20 61 6e 20 61 70 70  ccess and an app
35b90 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
35ba0 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65  code] on failure
35bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 32 31 7d  ..**.** {F17821}
35bc0 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   If an error occ
35bd0 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75  urs during evalu
35be0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
35bf0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 44 2c 2e 2e  3_blob_open(D,..
35c00 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
35c10 74 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20  then subsequent 
35c20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
35c30 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a  3_errcode(D)],.*
35c40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35c50 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20  te3_errmsg(D)], 
35c60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
35c70 6d 73 67 31 36 28 44 29 5d 20 77 69 6c 6c 20 72  msg16(D)] will r
35c80 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
35c90 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70    information ap
35ca0 70 72 6f 70 72 61 74 65 20 66 6f 72 20 74 68 61  proprate for tha
35cb0 74 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  t error..*/.int 
35cc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
35cd0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
35ce0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
35cf0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
35d00 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
35d10 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
35d20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
35d30 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
35d40 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
35d50 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
35d60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 43  .** CAPI3REF:  C
35d70 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
35d80 6c 65 20 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a  le {F17830}.**.*
35d90 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20  * Close an open 
35da0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
35db0 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a  blob handle]..**
35dc0 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c  .** Closing a BL
35dd0 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74  OB shall cause t
35de0 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  he current trans
35df0 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74  action to commit
35e00 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65  .** if there are
35e10 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c   no other BLOBs,
35e20 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70   no pending prep
35e30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c  ared statements,
35e40 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61   and the.** data
35e50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35e60 69 73 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  is in autocommit
35e70 20 6d 6f 64 65 2e 0a 2a 2a 20 49 66 20 61 6e 79   mode..** If any
35e80 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
35e90 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
35ea0 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
35eb0 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
35ec0 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
35ed0 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
35ee0 77 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a  will fit. {END}.
35ef0 2a 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42  ** Closing the B
35f00 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
35f10 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
35f20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
35f30 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
35f40 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
35f50 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
35f60 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
35f70 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
35f80 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37  is closed.  {F17
35f90 38 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20  833} Any errors 
35fa0 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e  that occur durin
35fb0 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65  g.** closing are
35fc0 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e   reported as a n
35fd0 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76  on-zero return v
35fe0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
35ff0 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
36000 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
36010 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
36020 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
36030 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
36040 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
36050 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  l closed..**.** 
36060 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
36070 2a 20 7b 46 31 37 38 33 33 7d 20 54 68 65 20 5b  * {F17833} The [
36080 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
36090 73 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  se(P)] interface
360a0 20 63 6c 6f 73 65 73 20 61 6e 0a 2a 2a 20 20 20   closes an.**   
360b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
360c0 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 20 50 20 70  blob] object P p
360d0 72 65 76 69 6f 75 73 6c 79 20 6f 70 65 6e 65 64  reviously opened
360e0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
360f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62     [sqlite3_blob
36100 5f 6f 70 65 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _open()]..**.** 
36110 7b 46 31 37 38 33 36 7d 20 43 6c 6f 73 69 6e 67  {F17836} Closing
36120 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   an [sqlite3_blo
36130 62 5d 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 0a  b] object using.
36140 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
36150 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
36160 29 5d 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74  )] shall cause t
36170 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  he current trans
36180 61 63 74 69 6f 6e 20 74 6f 0a 2a 2a 20 20 20 20  action to.**    
36190 20 20 20 20 20 20 63 6f 6d 6d 69 74 20 69 66 20        commit if 
361a0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
361b0 65 72 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  er open [sqlite3
361c0 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63 74 73 0a 2a  _blob] objects.*
361d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70  *          or [p
361e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
361f0 74 73 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ts] on the same 
36200 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36210 74 69 6f 6e 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  tion] and.**    
36220 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62        the [datab
36230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36240 69 73 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  is in.**        
36250 20 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61    [sqlite3_get_a
36260 75 74 6f 63 6f 6d 6d 69 74 20 7c 20 61 75 74 6f  utocommit | auto
36270 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a  commit mode]..**
36280 0a 2a 2a 20 7b 46 31 37 38 33 39 7d 20 54 68 65  .** {F17839} The
36290 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
362a0 6c 6f 73 65 28 50 29 5d 20 69 6e 74 65 72 66 61  lose(P)] interfa
362b0 63 65 73 20 63 6c 6f 73 65 73 20 74 68 65 20 0a  ces closes the .
362c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
362d0 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a 65 63  ite3_blob] objec
362e0 74 20 50 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  t P unconditiona
362f0 6c 6c 79 2c 20 65 76 65 6e 20 69 66 0a 2a 2a 20  lly, even if.** 
36300 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36310 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 50 29 5d  3_blob_close(P)]
36320 20 72 65 74 75 72 6e 73 20 73 6f 6d 65 74 68 69   returns somethi
36330 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
36340 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 20 20  QLITE_OK]..**   
36350 20 20 20 20 20 20 20 0a 2a 2f 0a 69 6e 74 20 73         .*/.int s
36360 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
36370 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
36380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36390 45 46 3a 20 20 52 65 74 75 72 6e 20 54 68 65 20  EF:  Return The 
363a0 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20  Size Of An Open 
363b0 42 4c 4f 42 20 7b 46 31 37 38 34 30 7d 0a 2a 2a  BLOB {F17840}.**
363c0 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73  .** Return the s
363d0 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20  ize in bytes of 
363e0 74 68 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69  the blob accessi
363f0 62 6c 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e  ble via the open
36400 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
36410 6f 62 5d 20 6f 62 6a 65 63 74 20 69 6e 20 69 74  ob] object in it
36420 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  s only argument.
36430 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
36440 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 34 33  S:.**.** {F17843
36450 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
36460 6c 6f 62 5f 62 79 74 65 73 28 50 29 5d 20 69 6e  lob_bytes(P)] in
36470 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36480 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20  the size.**     
36490 20 20 20 20 20 69 6e 20 62 79 74 65 73 20 6f 66       in bytes of
364a0 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 74   the BLOB that t
364b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
364c0 5d 20 6f 62 6a 65 63 74 20 50 0a 2a 2a 20 20 20  ] object P.**   
364d0 20 20 20 20 20 20 20 72 65 66 65 72 73 20 74 6f         refers to
364e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
364f0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69  _blob_bytes(sqli
36500 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
36510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52  .** CAPI3REF:  R
36520 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
36530 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
36540 6c 79 20 7b 46 31 37 38 35 30 7d 0a 2a 2a 0a 2a  ly {F17850}.**.*
36550 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
36560 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  is used to read 
36570 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65  data from an ope
36580 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  n .** [sqlite3_b
36590 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c  lob | blob-handl
365a0 65 5d 20 69 6e 74 6f 20 61 20 63 61 6c 6c 65 72  e] into a caller
365b0 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72   supplied buffer
365c0 2e 0a 2a 2a 20 4e 20 62 79 74 65 73 20 6f 66 20  ..** N bytes of 
365d0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
365e0 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a 2a 20 5a  into buffer.** Z
365f0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 62   from the open b
36600 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74  lob, starting at
36610 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
36620 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74  .**.** If offset
36630 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
36640 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
36650 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
36660 65 20 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c  e blob, .** [SQL
36670 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
36680 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
36690 74 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20  ta is read.  If 
366a0 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a  N or iOffset is.
366b0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
366c0 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
366d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
366e0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
366f0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
36700 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  ss, SQLITE_OK is
36710 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65 72   returned. Other
36720 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20 5b 65 72  wise, an .** [er
36730 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
36740 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36750 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
36760 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
36770 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  NTS:.**.** {F178
36780 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
36790 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e  _blob_read(P,Z,N
367a0 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,X)] interface r
367b0 65 61 64 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20  eads N bytes.** 
367c0 20 20 20 20 20 20 20 20 20 62 65 67 69 6e 6e 69           beginni
367d0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 58 20 66  ng at offset X f
367e0 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
367f0 74 68 65 20 62 6c 6f 62 20 74 68 61 74 20 5b 73  the blob that [s
36800 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20 6f 62 6a  qlite3_blob] obj
36810 65 63 74 20 50 20 72 65 66 65 72 73 20 74 6f 0a  ect P refers to.
36820 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
36830 77 72 69 74 65 73 20 74 68 6f 73 65 20 4e 20 62  writes those N b
36840 79 74 65 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ytes into buffer
36850 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35   Z..**.** {F1785
36860 36 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 62  6} In [sqlite3_b
36870 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c 4e 2c 58  lob_read(P,Z,N,X
36880 29 5d 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  )] if the size o
36890 66 20 74 68 65 20 62 6c 6f 62 0a 2a 2a 20 20 20  f the blob.**   
368a0 20 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74         is less t
368b0 68 61 6e 20 4e 2b 58 20 62 79 74 65 73 2c 20 74  han N+X bytes, t
368c0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
368d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
368e0 5f 45 52 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20  _ERROR].**      
368f0 20 20 20 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20      and nothing 
36900 69 73 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65  is read from the
36910 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   blob..**.** {F1
36920 37 38 35 39 7d 20 49 6e 20 5b 73 71 6c 69 74 65  7859} In [sqlite
36930 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c  3_blob_read(P,Z,
36940 4e 2c 58 29 5d 20 69 66 20 58 20 6f 72 20 4e 20  N,X)] if X or N 
36950 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
36960 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  o.**          th
36970 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
36980 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36990 45 52 52 4f 52 5d 0a 2a 2a 20 20 20 20 20 20 20  ERROR].**       
369a0 20 20 20 61 6e 64 20 6e 6f 74 68 69 6e 67 20 69     and nothing i
369b0 73 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65 20  s read from the 
369c0 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  blob..**.** {F17
369d0 38 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  862} The [sqlite
369e0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 50 2c 5a 2c  3_blob_read(P,Z,
369f0 4e 2c 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,X)] interface 
36a00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36a10 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
36a20 69 66 20 4e 20 62 79 74 65 73 20 77 68 65 72 65  if N bytes where
36a30 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 72 65   successfully re
36a40 61 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a  ad into buffer Z
36a50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 36 35 7d  ..**.** {F17865}
36a60 20 49 66 20 74 68 65 20 72 65 71 75 65 73 74 65   If the requeste
36a70 64 20 72 65 61 64 20 63 6f 75 6c 64 20 6e 6f 74  d read could not
36a80 20 62 65 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a   be completed,.*
36a90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
36aa0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
36ab0 64 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65  d(P,Z,N,X)] inte
36ac0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 6e  rface returns an
36ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70  .**          app
36ae0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
36af0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
36b00 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
36b10 2a 2a 0a 2a 2a 20 7b 46 31 37 38 36 38 7d 20 49  **.** {F17868} I
36b20 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
36b30 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74  s during evaluat
36b40 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
36b50 62 6c 6f 62 5f 72 65 61 64 28 44 2c 2e 2e 2e 29  blob_read(D,...)
36b60 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ].**          th
36b70 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  en subsequent ca
36b80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36b90 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20  errcode(D)],.** 
36ba0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36bb0 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e  3_errmsg(D)], an
36bc0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
36bd0 67 31 36 28 44 29 5d 20 77 69 6c 6c 20 72 65 74  g16(D)] will ret
36be0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
36bf0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72  information appr
36c00 6f 70 72 61 74 65 20 66 6f 72 20 74 68 61 74 20  oprate for that 
36c10 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  error..*/.int sq
36c20 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
36c30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
36c40 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20  void *Z, int N, 
36c50 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
36c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
36c70 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
36c80 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
36c90 61 6c 6c 79 20 7b 46 31 37 38 37 30 7d 0a 2a 2a  ally {F17870}.**
36ca0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
36cb0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
36cc0 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
36cd0 6f 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  open .** [sqlite
36ce0 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61  3_blob | blob-ha
36cf0 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 20 75 73 65  ndle] from a use
36d00 72 20 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r supplied buffe
36d10 72 2e 0a 2a 2a 20 6e 20 62 79 74 65 73 20 6f 66  r..** n bytes of
36d20 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
36d30 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
36d40 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
36d50 79 20 7a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  y z into the ope
36d60 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67  n blob, starting
36d70 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
36d80 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  et..**.** If the
36d90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
36da0 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61   blob-handle] pa
36db0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
36dc0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61  t argument.** wa
36dd0 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72  s not opened for
36de0 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c   writing (the fl
36df0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
36e00 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
36e10 70 65 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a  pen()].*** was z
36e20 65 72 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74  ero), this funct
36e30 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
36e40 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
36e50 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
36e60 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
36e70 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
36e80 6f 66 20 74 68 65 20 62 6c 6f 62 3b 20 69 74 20  of the blob; it 
36e90 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
36ea0 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
36eb0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
36ec0 62 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  b using this API
36ed0 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69  ..** If offset i
36ee0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
36ef0 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d  han n bytes from
36f00 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
36f10 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  blob, .** [SQLIT
36f20 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
36f30 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
36f40 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66   is written.  If
36f50 20 6e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   n is.** less th
36f60 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
36f70 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
36f80 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
36f90 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a  s written..**.**
36fa0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51 4c   On success, SQL
36fb0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
36fc0 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 61  ed. Otherwise, a
36fd0 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  n .** [error cod
36fe0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
36ff0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
37000 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
37010 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
37020 0a 2a 2a 20 7b 46 31 37 38 37 33 7d 20 54 68 65  .** {F17873} The
37030 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
37040 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69  rite(P,Z,N,X)] i
37050 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
37060 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
37070 20 20 20 20 66 72 6f 6d 20 62 75 66 66 65 72 20      from buffer 
37080 5a 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 20  Z into.**       
37090 20 20 20 74 68 65 20 62 6c 6f 62 20 74 68 61 74     the blob that
370a0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d 20   [sqlite3_blob] 
370b0 6f 62 6a 65 63 74 20 50 20 72 65 66 65 72 73 20  object P refers 
370c0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  to.**          b
370d0 65 67 69 6e 6e 69 6e 67 20 61 74 20 61 6e 20 6f  eginning at an o
370e0 66 66 73 65 74 20 6f 66 20 58 20 69 6e 74 6f 20  ffset of X into 
370f0 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  the blob..**.** 
37100 7b 46 31 37 38 37 35 7d 20 54 68 65 20 5b 73 71  {F17875} The [sq
37110 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
37120 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72  (P,Z,N,X)] inter
37130 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
37140 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
37150 5f 52 45 41 44 4f 4e 4c 59 5d 20 69 66 20 74 68  _READONLY] if th
37160 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5d  e [sqlite3_blob]
37170 20 6f 62 6a 65 63 74 20 50 20 77 61 73 0a 2a 2a   object P was.**
37180 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
37190 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 6f  e3_blob_open | o
371a0 70 65 6e 65 64 5d 20 66 6f 72 20 72 65 61 64 69  pened] for readi
371b0 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ng only..**.** {
371c0 46 31 37 38 37 36 7d 20 49 6e 20 5b 73 71 6c 69  F17876} In [sqli
371d0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 50  te3_blob_write(P
371e0 2c 5a 2c 4e 2c 58 29 5d 20 69 66 20 74 68 65 20  ,Z,N,X)] if the 
371f0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 62  size of the blob
37200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37210 6c 65 73 73 20 74 68 61 6e 20 4e 2b 58 20 62 79  less than N+X by
37220 74 65 73 2c 20 74 68 65 6e 20 74 68 65 20 66 75  tes, then the fu
37230 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
37240 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 0a 2a 2a  SQLITE_ERROR].**
37250 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6e 6f            and no
37260 74 68 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  thing is written
37270 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f 62 2e 0a   into the blob..
37280 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37 39 7d 20 49  **.** {F17879} I
37290 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  n [sqlite3_blob_
372a0 77 72 69 74 65 28 50 2c 5a 2c 4e 2c 58 29 5d 20  write(P,Z,N,X)] 
372b0 69 66 20 58 20 6f 72 20 4e 20 69 73 20 6c 65 73  if X or N is les
372c0 73 20 74 68 61 6e 20 7a 65 72 6f 0a 2a 2a 20 20  s than zero.**  
372d0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
372e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
372f0 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  s [SQLITE_ERROR]
37300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
37310 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69 74   nothing is writ
37320 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 6c 6f  ten into the blo
37330 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 38 32  b..**.** {F17882
37340 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
37350 6c 6f 62 5f 77 72 69 74 65 28 50 2c 5a 2c 4e 2c  lob_write(P,Z,N,
37360 58 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  X)] interface re
37370 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
37380 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  ].**          if
37390 20 4e 20 62 79 74 65 73 20 77 68 65 72 65 20 73   N bytes where s
373a0 75 63 63 65 73 73 66 75 6c 6c 79 20 77 72 69 74  uccessfully writ
373b0 74 65 6e 20 69 6e 74 6f 20 62 6c 6f 62 2e 0a 2a  ten into blob..*
373c0 2a 0a 2a 2a 20 7b 46 31 37 38 38 35 7d 20 49 66  *.** {F17885} If
373d0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 77   the requested w
373e0 72 69 74 65 20 63 6f 75 6c 64 20 6e 6f 74 20 62  rite could not b
373f0 65 20 63 6f 6d 70 6c 65 74 65 64 2c 0a 2a 2a 20  e completed,.** 
37400 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
37410 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
37420 28 50 2c 5a 2c 4e 2c 58 29 5d 20 69 6e 74 65 72  (P,Z,N,X)] inter
37430 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 6e 0a  face returns an.
37440 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72  **          appr
37450 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
37460 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
37470 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
37480 2a 0a 2a 2a 20 7b 46 31 37 38 38 38 7d 20 49 66  *.** {F17888} If
37490 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
374a0 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69   during evaluati
374b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 62  on of [sqlite3_b
374c0 6c 6f 62 5f 77 72 69 74 65 28 44 2c 2e 2e 2e 29  lob_write(D,...)
374d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ].**          th
374e0 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  en subsequent ca
374f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37500 65 72 72 63 6f 64 65 28 44 29 5d 2c 0a 2a 2a 20  errcode(D)],.** 
37510 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
37520 33 5f 65 72 72 6d 73 67 28 44 29 5d 2c 20 61 6e  3_errmsg(D)], an
37530 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
37540 67 31 36 28 44 29 5d 20 77 69 6c 6c 20 72 65 74  g16(D)] will ret
37550 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
37560 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 70 70 72  information appr
37570 6f 70 72 61 74 65 20 66 6f 72 20 74 68 61 74 20  oprate for that 
37580 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  error..*/.int sq
37590 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
375a0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
375b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
375c0 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
375d0 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
375e0 33 52 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46  3REF:  Virtual F
375f0 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
37600 74 73 20 7b 46 31 31 32 30 30 7d 0a 2a 2a 0a 2a  ts {F11200}.**.*
37610 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c 65  * A virtual file
37620 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73 20  system (VFS) is 
37630 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
37640 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20   object.** that 
37650 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20 69  SQLite uses to i
37660 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68 20  nteract.** with 
37670 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
37680 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
37690 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62 75    Most SQLite bu
376a0 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61  ilds come with a
376b0 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75  .** single defau
376c0 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61  lt VFS that is a
376d0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74  ppropriate for t
376e0 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
376f0 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63  ..** New VFSes c
37700 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
37710 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46   and existing VF
37720 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67  Ses can be unreg
37730 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20  istered..** The 
37740 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66  following interf
37750 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
37760 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
37770 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20  ite3_vfs_find() 
37780 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37790 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a  s a pointer to .
377a0 2a 2a 20 61 20 56 46 53 20 67 69 76 65 6e 20 69  ** a VFS given i
377b0 74 73 20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20  ts name.  Names 
377c0 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69  are case sensiti
377d0 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65  ve..** Names are
377e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
377f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
37800 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  ** If there is n
37810 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a  o match, a NULL.
37820 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  ** pointer is re
37830 74 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73  turned.  If zVfs
37840 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
37850 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a  n the default .*
37860 2a 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  * VFS is returne
37870 64 2e 20 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46  d. .**.** New VF
37880 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
37890 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
378a0 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
378b0 2a 2a 20 45 61 63 68 20 6e 65 77 20 56 46 53 20  ** Each new VFS 
378c0 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
378d0 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
378e0 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
378f0 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
37900 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
37910 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
37920 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
37930 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
37940 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
37950 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
37960 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
37970 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
37980 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
37990 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
379a0 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
379b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
379c0 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
379d0 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
379e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
379f0 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
37a00 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
37a10 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
37a20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
37a30 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
37a40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
37a50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a   undefined..** .
37a60 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20  ** Unregister a 
37a70 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c  VFS with the sql
37a80 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
37a90 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  ter() interface.
37aa0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75  .** If the defau
37ab0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
37ac0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
37ad0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
37ae0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
37af0 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
37b00 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
37b10 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
37b20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
37b30 2a 2a 20 7b 46 31 31 32 30 33 7d 20 54 68 65 20  ** {F11203} The 
37b40 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
37b50 64 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  d(N)] interface 
37b60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37b70 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  r to the.**     
37b80 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
37b90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37ba0 6a 65 63 74 20 77 68 6f 73 65 20 6e 61 6d 65 20  ject whose name 
37bb0 65 78 61 63 74 6c 79 20 6d 61 74 63 68 65 73 0a  exactly matches.
37bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
37bd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
37be0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20  UTF-8 string N, 
37bf0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
37c00 4c 4c 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  LL if.**        
37c10 20 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61    there is no ma
37c20 74 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32  tch..**.** {F112
37c30 30 36 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72  06} If the N par
37c40 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
37c50 65 33 5f 76 66 73 5f 66 69 6e 64 28 4e 29 5d 20  e3_vfs_find(N)] 
37c60 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20  is NULL then.** 
37c70 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e           the fun
37c80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
37c90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 64  pointer to the d
37ca0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
37cb0 76 66 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  vfs].**         
37cc0 20 6f 62 6a 65 63 74 20 69 66 20 74 68 65 72 65   object if there
37cd0 20 69 73 20 6f 6e 65 2c 20 6f 72 20 4e 55 4c 4c   is one, or NULL
37ce0 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
37cf0 64 65 66 61 75 6c 74 20 0a 2a 2a 20 20 20 20 20  default .**     
37d00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66       [sqlite3_vf
37d10 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
37d20 20 7b 46 31 31 32 30 39 7d 20 54 68 65 20 5b 73   {F11209} The [s
37d30 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
37d40 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66  ter(P,F)] interf
37d50 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68  ace registers th
37d60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 65  e.**          we
37d70 6c 6c 2d 66 6f 72 6d 65 64 20 5b 73 71 6c 69 74  ll-formed [sqlit
37d80 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 50  e3_vfs] object P
37d90 20 75 73 69 6e 67 20 74 68 65 20 6e 61 6d 65 20   using the name 
37da0 67 69 76 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20  given.**        
37db0 20 20 62 79 20 74 68 65 20 7a 4e 61 6d 65 20 66    by the zName f
37dc0 69 65 6c 64 20 6f 66 20 74 68 65 20 6f 62 6a 65  ield of the obje
37dd0 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31  ct..**.** {F1121
37de0 32 7d 20 55 73 69 6e 67 20 74 68 65 20 5b 73 71  2} Using the [sq
37df0 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
37e00 65 72 28 50 2c 46 29 5d 20 69 6e 74 65 72 66 61  er(P,F)] interfa
37e10 63 65 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  ce to register.*
37e20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
37e30 61 6d 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ame [sqlite3_vfs
37e40 5d 20 6f 62 6a 65 63 74 20 6d 75 6c 74 69 70 6c  ] object multipl
37e50 65 20 74 69 6d 65 73 20 69 73 20 61 20 68 61 72  e times is a har
37e60 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
37e70 2a 2a 20 7b 46 31 31 32 31 35 7d 20 54 68 65 20  ** {F11215} The 
37e80 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
37e90 69 73 74 65 72 28 50 2c 46 29 5d 20 69 6e 74 65  ister(P,F)] inte
37ea0 72 66 61 63 65 20 6d 61 6b 65 73 20 74 68 65 0a  rface makes the.
37eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
37ec0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37ed0 6a 65 63 74 20 50 20 74 68 65 20 64 65 66 61 75  ject P the defau
37ee0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
37ef0 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
37f00 20 20 20 20 69 66 20 46 20 69 73 20 6e 6f 6e 2d      if F is non-
37f10 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  zero..**.** {F11
37f20 32 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  218} The [sqlite
37f30 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
37f40 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 75  (P)] interface u
37f50 6e 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a  nregisters the.*
37f60 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37f70 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
37f80 50 20 73 6f 20 74 68 61 74 20 69 74 20 69 73 20  P so that it is 
37f90 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 74 75 72 6e  no longer return
37fa0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
37fb0 20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c    subsequent cal
37fc0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ls to [sqlite3_v
37fd0 66 73 5f 66 69 6e 64 28 29 5d 2e 0a 2a 2f 0a 73  fs_find()]..*/.s
37fe0 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
37ff0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
38000 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
38010 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
38020 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
38030 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
38040 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
38050 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
38060 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
38070 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
38080 52 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 46 31  REF: Mutexes {F1
38090 37 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7000}.**.** The 
380a0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
380b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
380c0 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79  for thread.** sy
380d0 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 20  nchronization.  
380e0 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
380f0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
38100 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
38110 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
38120 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
38130 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
38140 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
38150 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
38160 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
38170 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
38180 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
38190 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
381a0 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ons .** of these
381b0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
381c0 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
381d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
381e0 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
381f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
38200 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54  compile-time.  T
38210 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
38220 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
38230 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  are available in
38240 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
38250 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
38260 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
38270 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_OS2.** <li> 
38280 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50    SQLITE_MUTEX_P
38290 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20  THREAD.** <li>  
382a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
382b0 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  2.** <li>   SQLI
382c0 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a  TE_MUTEX_NOOP.**
382d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
382e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
382f0 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  OP implementatio
38300 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f  n is a set of ro
38310 75 74 69 6e 65 73 20 0a 2a 2a 20 74 68 61 74 20  utines .** that 
38320 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63  does no real loc
38330 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72  king and is appr
38340 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
38350 69 6e 20 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d  in .** a single-
38360 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
38370 74 69 6f 6e 2e 20 20 54 68 65 20 53 51 4c 49 54  tion.  The SQLIT
38380 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
38390 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
383a0 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
383b0 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
383c0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
383d0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
383e0 72 20 75 73 65 20 6f 6e 20 6f 73 2f 32 2c 20 75  r use on os/2, u
383f0 6e 69 78 2c 20 61 6e 64 20 77 69 6e 64 6f 77 73  nix, and windows
38400 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 53 51 4c 69  ..** .** If SQLi
38410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
38420 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
38430 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
38440 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
38450 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
38460 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
38470 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
38480 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
38490 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
384a0 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
384b0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 0a 2a   library.  The.*
384c0 2a 20 6d 75 74 65 78 20 69 6e 74 65 72 66 61 63  * mutex interfac
384d0 65 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  e routines defin
384e0 65 64 20 68 65 72 65 20 62 65 63 6f 6d 65 20 65  ed here become e
384f0 78 74 65 72 6e 61 6c 0a 2a 2a 20 72 65 66 65 72  xternal.** refer
38500 65 6e 63 65 73 20 69 6e 20 74 68 65 20 53 51 4c  ences in the SQL
38510 69 74 65 20 6c 69 62 72 61 72 79 20 66 6f 72 20  ite library for 
38520 77 68 69 63 68 20 69 6d 70 6c 65 6d 65 6e 74 61  which implementa
38530 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 62 65  tions.** must be
38540 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
38550 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
38560 68 69 73 20 66 61 63 69 6c 69 74 79 20 61 6c 6c  his facility all
38570 6f 77 73 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63  ows an.** applic
38580 61 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73  ation that links
38590 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20   against SQLite 
385a0 74 6f 20 70 72 6f 76 69 64 65 20 69 74 73 20 6f  to provide its o
385b0 77 6e 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  wn mutex.** impl
385c0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 6f  ementation witho
385d0 75 74 20 68 61 76 69 6e 67 20 74 6f 20 6d 6f 64  ut having to mod
385e0 69 66 79 20 74 68 65 20 53 51 4c 69 74 65 20 63  ify the SQLite c
385f0 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30  ore..**.** {F170
38600 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  11} The sqlite3_
38610 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f  mutex_alloc() ro
38620 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20  utine allocates 
38630 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61  a new.** mutex a
38640 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
38650 6e 74 65 72 20 74 6f 20 69 74 2e 20 7b 46 31 37  nter to it. {F17
38660 30 31 32 7d 20 49 66 20 69 74 20 72 65 74 75 72  012} If it retur
38670 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20  ns NULL.** that 
38680 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74  means that a mut
38690 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ex could not be 
386a0 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 46 31 37 30  allocated. {F170
386b0 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  13} SQLite.** wi
386c0 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74  ll unwind its st
386d0 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ack and return a
386e0 6e 20 65 72 72 6f 72 2e 20 7b 46 31 37 30 31 34  n error. {F17014
386f0 7d 20 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  } The argument.*
38700 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
38710 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
38720 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
38730 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
38740 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
38750 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
38760 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
38770 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
38780 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
38790 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
387a0 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
387b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
387c0 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
387d0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
387e0 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
387f0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
38800 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
38810 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
38820 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
38830 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a   </ul> {END}.**.
38840 2a 2a 20 7b 46 31 37 30 31 35 7d 20 54 68 65 20  ** {F17015} The 
38850 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61  first two consta
38860 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69 74 65  nts cause sqlite
38870 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
38880 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e  to create.** a n
38890 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65 20 6e  ew mutex.  The n
388a0 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75  ew mutex is recu
388b0 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54  rsive when SQLIT
388c0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
388d0 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74  E.** is used but
388e0 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79   not necessarily
388f0 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f   so when SQLITE_
38900 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73  MUTEX_FAST is us
38910 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65  ed. {END}.** The
38920 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
38930 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
38940 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
38950 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
38960 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
38970 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
38980 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
38990 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
389a0 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 7b 46  not want to.  {F
389b0 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c 69 74  17016} But SQLit
389c0 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75  e will only requ
389d0 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20  est a recursive 
389e0 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65  mutex in.** case
389f0 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c  s where it reall
38a00 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 7b 45  y needs one.  {E
38a10 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65 72 20  ND} If a f