/ Hex Artifact Content
Login

Artifact 31b526c2527b46575c3596a4cef0a046137f8a59:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 33 32 34 20 32 30 30 38 2f  in,v 1.324 2008/
05f0: 30 36 2f 31 30 20 31 37 3a 34 31 3a 34 35 20 64  06/10 17:41:45 d
0600: 72 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e  rh Exp $.*/.#ifn
0610: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
0620: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
0630: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
0640: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
0650: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
0660: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
0670: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
0680: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
0690: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
06a0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64  rom C++..*/.#ifd
06b0: 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65  ef __cplusplus.e
06c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
06d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
06e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
06f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
0700: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0710: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
0720: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
0730: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f  extern.#endif../
0740: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 74  *.** Make sure t
0750: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 68 65  hese symbols whe
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 2e 0a  header.** file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10010}.**.** Th
0850: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0860: 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53   and SQLITE_VERS
0870: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0880: 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71  nes in.** the sq
0890: 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65  lite3.h file spe
08a0: 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e  cify the version
08b0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 20   of SQLite with 
08c0: 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65  which.** that he
08d0: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73  ader file is ass
08e0: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  ociated..**.** T
08f0: 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20  he "version" of 
0900: 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 69  SQLite is a stri
0910: 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ng of the form "
0920: 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70  X.Y.Z"..** The p
0930: 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72  hrase "alpha" or
0940: 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 65   "beta" might be
0950: 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 20   appended after 
0960: 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20  the Z..** The X 
0970: 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76  value is major v
0980: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c  ersion number al
0990: 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65  ways 3 in SQLite
09a0: 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  3..** The X valu
09b0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  e only changes w
09c0: 68 65 6e 20 20 62 61 63 6b 77 61 72 64 73 20 63  hen  backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77 61   break.** backwa
0a10: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0a20: 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65 20  y.  The Y value 
0a30: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0a40: 73 69 6f 6e 0a 2a 2a 20 6e 75 6d 62 65 72 20 61  sion.** number a
0a50: 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  nd only changes 
0a60: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72  when.** there ar
0a70: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20  e major feature 
0a80: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61  enhancements tha
0a90: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63  t are forwards c
0aa0: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74  ompatible.** but
0ab0: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63   not backwards c
0ac0: 6f 6d 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20  ompatible.  The 
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 72 65 6c 65 61  Z value is relea
0ae0: 73 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 61 6e 64  se number.** and
0af0: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0b00: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0b10: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0b20: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 20 59  back to 0 when Y
0b30: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e   is incremented.
0b40: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
0b50: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b60: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
0b70: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
0b80: 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a  number()]..**.**
0b90: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
0ba0: 2a 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20  ** {F10011} The 
0bb0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23  SQLITE_VERSION #
0bc0: 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71  define in the sq
0bd0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66  lite3.h header f
0be0: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
0bf0: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0c00: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0c10: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0c20: 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20   version.**     
0c30: 20 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20       with which 
0c40: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
0c50: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0c60: 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68  *.** {F10014} Th
0c70: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c80: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0c90: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
0ca0: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0cb0: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0cc0: 65 20 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  e  (X*1000000 + 
0cd0: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
0ce0: 65 20 58 2c 20 59 2c 20 61 6e 64 0a 2a 2a 20 20  e X, Y, and.**  
0cf0: 20 20 20 20 20 20 20 20 5a 20 61 72 65 20 74 68          Z are th
0d00: 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c  e major version,
0d10: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20   minor version, 
0d20: 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62  and release numb
0d30: 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  er..*/.#define S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
0d50: 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22        "--VERS--"
0d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0d70: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20  VERSION_NUMBER  
0d80: 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52  --VERSION-NUMBER
0d90: 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  --../*.** CAPI3R
0da0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0db0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0dc0: 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a  bers {F10020}.**
0dd0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
0de0: 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  e3_version.**.**
0df0: 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20   These features 
0e00: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
0e10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0e20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
0e30: 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  ION].** and [SQL
0e40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0e50: 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20  ER] #defines in 
0e60: 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20  the header, but 
0e70: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  are associated.*
0e80: 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  * with the libra
0e90: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
0ea0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
0eb0: 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d  Cautious program
0ec0: 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e  mers might.** in
0ed0: 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e  clude a check in
0ee0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
0ef0: 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  on to verify tha
0f00: 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  t .** sqlite3_li
0f10: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0f20: 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  ) always returns
0f30: 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 5b   the value .** [
0f40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0f50: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
0f60: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0f70: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
0f80: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
0f90: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0fa0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
0fb0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0fc0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
0fd0: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
0fe0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
0ff0: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1000: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1010: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1020: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1030: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1040: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1050: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   DLL..**.** INVA
1060: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1070: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
1080: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
1090: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
10a0: 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ce returns an in
10b0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
10c0: 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49    equal to [SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
10e0: 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30  R]. .**.** {F100
10f0: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
1100: 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67  _version] string
1110: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
1120: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
1130: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1140: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
1150: 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a 20 7b  string. .**.** {
1160: 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  F10023} The [sql
1170: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1180: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
1190: 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
11a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11b0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11c0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11d0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
11e0: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
11f0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1200: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1210: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1220: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1230: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1240: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1260: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1270: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1280: 65 61 64 73 61 66 65 20 7b 46 31 30 31 30 30 7d  eadsafe {F10100}
1290: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
12a0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
12b0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
12c0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
12d0: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
12e0: 44 53 41 46 45 20 43 20 70 72 65 70 72 6f 63 65  DSAFE C preproce
12f0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72  ssor macro is tr
1300: 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  ue, mutexes.** a
1310: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1320: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1330: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20  afe.  When that 
1340: 6d 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a  macro is false,.
1350: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1360: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1370: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1380: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1390: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
13a0: 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  e from more than
13b0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
13c0: 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20 6d 65  ** There is a me
13d0: 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d  asurable perform
13e0: 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66 6f 72  ance penalty for
13f0: 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65   enabling mutexe
1400: 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  s..** So if spee
1410: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
1420: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
1430: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
1440: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
1450: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
1460: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
1470: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
1480: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20  enabled..** The 
1490: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
14a0: 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20   is for mutexes 
14b0: 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  to be enabled..*
14c0: 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
14d0: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
14e0: 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20  by a program to 
14f0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1500: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1510: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1520: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1530: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1540: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1550: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1560: 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44  he SQLITE_THREAD
1570: 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  SAFE macro..**.*
1580: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1590: 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68 65  .** {F10101} The
15a0: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
15b0: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  safe()] function
15c0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72 6f   returns nonzero
15d0: 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
15e0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
15f0: 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75 74  led with its mut
1600: 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72 20  exes enabled or 
1610: 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  zero.**         
1620: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
1630: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1640: 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  exes disabled..*
1650: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  /.int sqlite3_th
1660: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
1670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1680: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1690: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31  ction Handle {F1
16a0: 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  2000}.** KEYWORD
16b0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
16c0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
16d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
16e0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
16f0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1700: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1710: 79 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  y pointer to an 
1720: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 0a  instance of the.
1730: 2a 2a 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  ** opaque struct
1740: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1750: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1760: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1770: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1780: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1790: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
17a0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
17b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
17c0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
17d0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
17e0: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
17f0: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20  tructors.** and 
1800: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1810: 5d 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  ] is its destruc
1820: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
1830: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
1840: 66 61 63 65 73 0a 2a 2a 20 28 73 75 63 68 20 61  faces.** (such a
1850: 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1860: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1870: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1880: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1890: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18a0: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
18b0: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
18c0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68  re methods on th
18d0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f  is.** object..*/
18e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
18f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
1900: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1910: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
1920: 72 20 54 79 70 65 73 20 7b 46 31 30 32 30 30 7d  r Types {F10200}
1930: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1940: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1950: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
1960: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
1970: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
1980: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
1990: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
19a0: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
19b0: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
19c0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
19d0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
19e0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
19f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
1a00: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
1a10: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
1a20: 65 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20  eferred type.** 
1a30: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68  definitions.  Th
1a40: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
1a50: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
1a60: 20 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75   types are.** su
1a70: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1a80: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1a90: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
1aa0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ab0: 2a 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b  * {F10201} The [
1ac0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e  sqlite_int64] an
1ad0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d [sqlite3_int64
1ae0: 5d 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20  ] types specify 
1af0: 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34  a.**          64
1b00: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1b10: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  ger..**.** {F102
1b20: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1b30: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1b40: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1b50: 65 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20  es specify.**   
1b60: 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20         a 64-bit 
1b70: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1b80: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
1b90: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
1ba0: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
1bb0: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
1bc0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
1bd0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
1be0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
1bf0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
1c00: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
1c10: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
1c20: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
1c30: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
1c40: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1c50: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1c60: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
1c70: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
1c80: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
1c90: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
1ca0: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
1cb0: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
1cc0: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
1cd0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
1ce0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
1cf0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
1d00: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
1d10: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
1d20: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
1d30: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
1d40: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
1d50: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
1d60: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
1d70: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
1d80: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
1d90: 69 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  int.*/.#ifdef SQ
1da0: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
1db0: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
1dc0: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
1dd0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
1de0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1df0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
1e00: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31  e Connection {F1
1e10: 32 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2010}.**.** This
1e20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
1e30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
1e40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1e50: 65 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70  ect.  .**.** App
1e60: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
1e70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e80: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
1e90: 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  ll.** [prepared 
1ea0: 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a  statements] and.
1eb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
1ec0: 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20  _close | close] 
1ed0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  all [sqlite3_blo
1ee0: 62 20 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61  b | BLOBs] .** a
1ef0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1f00: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1f10: 65 63 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20  ect prior.** to 
1f20: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
1f30: 6f 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ose the [sqlite3
1f40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
1f50: 3c 74 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65  <todo>What happe
1f60: 6e 73 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72  ns to pending tr
1f70: 61 6e 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65  ansactions?  Are
1f80: 20 74 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20   they.** rolled 
1f90: 62 61 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e  back, or abandon
1fa0: 65 64 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ed?</todo>.**.**
1fb0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1fc0: 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20  ** {F12011} The 
1fd0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1fe0: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
1ff0: 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  roys an [sqlite3
2000: 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20  ] object.**     
2010: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
2020: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
2030: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2040: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2050: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2060: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2070: 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
2080: 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b  * {F12012} The [
2090: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
20a0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73   function releas
20b0: 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73  es all memory us
20c0: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
20d0: 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
20e0: 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20   and closes all 
20f0: 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  open files..**.*
2100: 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68  * {F12013} If th
2110: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2120: 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a  ction contains.*
2130: 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2140: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2150: 20 74 68 61 74 20 68 61 76 65 20 6e 6f 74 20 62   that have not b
2160: 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
2170: 66 69 6e 61 6c 69 7a 65 64 20 62 79 20 5b 73 71  finalized by [sq
2180: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2190: 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
21a0: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20  _close()].**    
21b0: 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 5b 53        returns [S
21c0: 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
21d0: 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 6e 65  leaves the conne
21e0: 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a  ction open..**.*
21f0: 2a 20 7b 46 31 32 30 31 34 7d 20 47 69 76 69 6e  * {F12014} Givin
2200: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
2210: 29 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ) a NULL pointer
2220: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
2230: 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  o-op..**.** LIMI
2240: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
2250: 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61  U12015} The para
2260: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2270: 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20  3_close()] must 
2280: 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  be an [sqlite3] 
2290: 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20  object.**       
22a0: 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69     pointer previ
22b0: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
22c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
22d0: 6e 28 29 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20  n()] or the .** 
22e0: 20 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c           equival
22f0: 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  ent, or NULL..**
2300: 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65  .** {U12016} The
2310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2320: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
2330: 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2340: 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  en previously.**
2350: 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64            closed
2360: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2370: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2380: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2390: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
23a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
23b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
23c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
23d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
23e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
23f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2400: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2410: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2420: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2430: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2440: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2450: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2460: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2470: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2480: 65 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a  erface {F12100}.
2490: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24a0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
24b0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
24c0: 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e  nt way of runnin
24d0: 67 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  g.** one or more
24e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
24f0: 77 69 74 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66  without a lot of
2500: 20 43 20 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a   C code.  The.**
2510: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2520: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2530: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
2550: 74 65 33 5f 65 78 65 63 28 29 2e 20 20 54 68 65  te3_exec().  The
2560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2570: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2580: 20 6f 6e 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69   one.** until ei
2590: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72  ther an error or
25a0: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
25b0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a   encountered or.
25c0: 2a 2a 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72  ** until they ar
25d0: 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65  e all done.  The
25e0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
25f0: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a  s an optional.**
2600: 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69   callback that i
2610: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
2620: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61  or each row of a
2630: 6e 79 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ny query results
2640: 0a 2a 2a 20 70 72 6f 64 75 63 65 64 20 62 79 20  .** produced by 
2650: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2660: 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  ts.  The 5th par
2670: 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65  ameter tells whe
2680: 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61  re.** to write a
2690: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
26a0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72  s..**.** The err
26b0: 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65  or message passe
26c0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
26d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
26e0: 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d   is held.** in m
26f0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2700: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2710: 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69  loc()].  To avoi
2720: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c  d a memory leak,
2730: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  .** the calling 
2740: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
2750: 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ld call [sqlite3
2760: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20  _free()] on any 
2770: 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2780: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
2790: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
27a0: 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  ter when it has 
27b0: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a  finished using.*
27c0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
27d0: 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  age..**.** If th
27e0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27f0: 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  in the 2nd param
2800: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20  eter is NULL or 
2810: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a  an empty string.
2820: 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63  ** or a string c
2830: 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77  ontaining only w
2840: 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f  hitespace and co
2850: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 53 51 4c  mments, then SQL
2860: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61  .** statements a
2870: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
2880: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2890: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
28a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
28b0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
28c0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e  s implemented in
28d0: 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71   terms of.** [sq
28e0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28f0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2900: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2910: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2920: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2930: 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64  exec() routine d
2940: 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74  oes nothing to t
2950: 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
2960: 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a   cannot be done.
2970: 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
2980: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
2990: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
29a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
29b0: 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  alize()]..**.** 
29c0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a  INVARIANTS:.** .
29d0: 2a 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73 75  ** {F12101} A su
29e0: 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
29f0: 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
2a00: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
2a10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
2a20: 6c 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ll evaluate all 
2a30: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
2a40: 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d  oded, semicolon-
2a50: 73 65 70 61 72 61 74 65 64 2c 0a 2a 2a 20 20 20  separated,.**   
2a60: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
2a70: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
2a80: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
2a90: 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65  ing S within the
2aa0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2ab0: 74 65 78 74 20 6f 66 20 74 68 65 20 44 20 5b 64  text of the D [d
2ac0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ad0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  on]..**.** {F121
2ae0: 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72  02} If the S par
2af0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2b00: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
2b10: 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  E)] is NULL then
2b20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2b30: 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20   actions of the 
2b40: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2b50: 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69  be the same as i
2b60: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2b70: 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 68    S parameter wh
2b80: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72  ere an empty str
2b90: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ing..**.** {F121
2ba0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
2bb0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
2bc0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
2bd0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  e [SQLITE_OK] if
2be0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2bf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2c00: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79  run successfully
2c10: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69   and to completi
2c20: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30  on..**.** {F1210
2c30: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  5} The return va
2c40: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
2c50: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65  exec()] shall be
2c60: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2c70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
2c80: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
2c90: 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74  e] if any SQL st
2ca0: 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a  atement fails..*
2cb0: 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66  *.** {F12107} If
2cc0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2cd0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2ce0: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
2cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
2d00: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2d10: 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65   results and the
2d20: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2d30: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
2d40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d50: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2d60: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
2d70: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2d80: 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20  r shall be.**   
2d90: 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f         invoked o
2da0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2db0: 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a   of result..**.*
2dc0: 2a 20 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68  * {F12110} If th
2dd0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
2de0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ns a non-zero va
2df0: 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  lue then [sqlite
2e00: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
2e10: 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72        shall abor
2e20: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
2e30: 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e  ent it is curren
2e40: 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a  tly evaluating,.
2e50: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70  **          skip
2e60: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
2e70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  SQL statements, 
2e80: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
2e90: 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
2ea0: 20 7b 46 31 32 31 31 33 7d 20 54 68 65 20 5b 73   {F12113} The [s
2eb0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
2ec0: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73  outine shall pas
2ed0: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
2ee0: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
2ef0: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
2f00: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
2f10: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2f20: 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65  .** {F12116} The
2f30: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2f40: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
2f50: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2f60: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
2f70: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
2f80: 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
2f90: 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2fa0: 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a  current row of.*
2fb0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
2fc0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39  t..**.** {F12119
2fd0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
2fe0: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
2ff0: 65 74 73 20 74 68 65 20 33 72 64 20 70 61 72 61  ets the 3rd para
3000: 6d 65 74 65 72 20 6f 66 20 69 74 73 20 0a 2a 2a  meter of its .**
3010: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3020: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3030: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3040: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3050: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3060: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
3070: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
3080: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
3090: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
30a0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
30b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
30c0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
30d0: 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65 20 5b  * {F12122} The [
30e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
30f0: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
3100: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   4th parameter o
3110: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
3120: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
3130: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3140: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3150: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
3160: 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f           names o
3170: 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
3180: 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   as obtained fro
3190: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
31a0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
31b0: 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74 68 65   {F12125} If the
31c0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
31e0: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
31f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3200: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e 65 76  ite3_exec()] nev
3210: 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c  er invokes a cal
3220: 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72  lback.  All quer
3230: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
3240: 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65 6e 74  sults are silent
3250: 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  ly discarded..**
3260: 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49 66 20  .** {F12131} If 
3270: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3280: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3290: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
32a0: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
32b0: 20 20 20 20 20 20 20 68 61 6e 64 65 64 20 69 6e         handed in
32c0: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
32d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
32e0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e  c(D,S,C,A,E)] an
32f0: 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  d if.**         
3300: 20 74 68 65 20 45 20 70 61 72 61 6d 65 74 65 72   the E parameter
3310: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
3320: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  en [sqlite3_exec
3330: 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a  ()] shall store.
3340: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a  **          in *
3350: 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  E an appropriate
3360: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77   error message w
3370: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
3380: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20  ry obtained.**  
3390: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71          from [sq
33a0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
33b0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20  .**.** {F12134} 
33c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
33d0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f  c(D,S,C,A,E)] ro
33e0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
33f0: 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
3400: 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e           *E to N
3410: 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20  ULL if E is not 
3420: 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61  NULL and there a
3430: 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  re no errors..**
3440: 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54 68 65  .** {F12137} The
3450: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3460: 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74  ,S,C,A,E)] funct
3470: 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ion shall set th
3480: 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
3490: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
34a0: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
34b0: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
34c0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
34d0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
34e0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
34f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3500: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38  ]..**.** {F12138
3510: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3520: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3530: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3540: 5d 20 69 73 20 61 20 6e 75 6c 6c 20 6f 72 20 65  ] is a null or e
3550: 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mpty.**         
3560: 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61   string or conta
3570: 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65  ins nothing othe
3580: 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
3590: 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 20 61 6e 64  e, comments, and
35a0: 2f 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  /or.**          
35b0: 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e  semicolons, then
35c0: 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c   results of [sql
35d0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
35e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35f0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3610: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
3620: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65        shall rese
3630: 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f  t to indicate no
3640: 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c   errors..**.** L
3650: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
3660: 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66  * {U12141} The f
3670: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
3680: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3690: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
36a0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
36b0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
36c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
36d0: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54  **.** {U12142} T
36e0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36f0: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
3700: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
3710: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3720: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3730: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20  running..** .** 
3740: 7b 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {U12143} The cal
3750: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
3760: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
3770: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
3780: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
3790: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
37a0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
37b0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
37c0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
37d0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
37e0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
37f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d  ..**.** {U12145}
3800: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
3810: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
3820: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3830: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3840: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
3850: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
3860: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
3870: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3880: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
3890: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
38a0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
38b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38c0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
38d0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
38e0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
38f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3900: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
3910: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
3920: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
3930: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3940: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
3950: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
3960: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3970: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
3980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3990: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
39a0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
39b0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
39c0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
39d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
39e0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
39f0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
3a00: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
3a10: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
3a20: 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45  s {F10210}.** KE
3a30: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
3a40: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
3a50: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 0a  error codes}.**.
3a60: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
3a70: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
3a80: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
3a90: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
3aa0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
3ab0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
3ac0: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
3ad0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
3ae0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
3af0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
3b00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
3b10: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
3b20: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3b30: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3b40: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3b50: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3b60: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3b70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b80: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3b90: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3ba0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3bb0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3bc0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3bd0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
3be0: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
3bf0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
3c00: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
3c10: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
3c20: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
3c30: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
3c40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
3c50: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
3c60: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
3c70: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
3c80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3c90: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
3ca0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
3cb0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
3cc0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3cd0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
3ce0: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
3cf0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
3d00: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
3d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
3d20: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
3d30: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
3d40: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3d50: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
3d60: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
3d70: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
3d80: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
3d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3da0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
3db0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
3dc0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
3dd0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
3de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3df0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
3e00: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
3e10: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
3e20: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
3e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
3e40: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
3e50: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
3e60: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
3e70: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
3e80: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
3e90: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
3ea0: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
3eb0: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
3ec0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ed0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
3ee0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
3ef0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
3f00: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
3f10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f20: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
3f30: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
3f40: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
3f50: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
3f60: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
3f70: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
3f80: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
3f90: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
3fa0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
3fb0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
3fc0: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
3fd0: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
3fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
3ff0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4000: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4010: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4030: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4040: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4050: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4060: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4070: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4080: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4090: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
40a0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
40c0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
40d0: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
40e0: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
40f0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4100: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4110: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4120: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4130: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4140: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4150: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4160: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4170: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4180: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4190: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
41a0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
41b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
41c0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
41d0: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
41e0: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
41f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4200: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4210: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4220: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4230: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4240: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4250: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4260: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4270: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4280: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4290: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42a0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
42b0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
42c0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
42d0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
42e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
42f0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4300: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4310: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4320: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4330: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4340: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4350: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4360: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30  esult Codes {F10
4370: 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  220}.** KEYWORDS
4380: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  : {extended erro
4390: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  r code} {extende
43a0: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a  d error codes}.*
43b0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
43c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
43d0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
43e0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
43f0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4400: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4410: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4420: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4430: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4440: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4450: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4460: 77 6e 20 74 68 61 74 0a 2a 2a 20 6d 61 6e 79 20  wn that.** many 
4470: 6f 66 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  of these result 
4480: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4490: 75 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  urse-grained.  T
44a0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
44b0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
44c0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
44d0: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
44e0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
44f0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4500: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4510: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4520: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4530: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4540: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4550: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4560: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4570: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4580: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4590: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
45a0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
45b0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
45c0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
45d0: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
45e0: 64 0a 2a 2a 20 66 6f 72 20 65 61 63 68 20 64 61  d.** for each da
45f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4600: 6e 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  n using the [sql
4610: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4620: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 0a 2a 2a  sult_codes()].**
4630: 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53 6f 6d   API..** .** Som
4640: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4650: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4660: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4670: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4680: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4690: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
46a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
46b0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
46c0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
46d0: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
46e0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
46f0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4700: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4710: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4720: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4730: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4740: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4750: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4760: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4770: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4780: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4790: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 20 0a 2a 2a  tly zero..** .**
47a0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
47b0: 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65 20  ** {F10223} The 
47c0: 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f  symbolic name fo
47d0: 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  r an extended re
47e0: 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79 73  sult code always
47f0: 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
4800: 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64 20        a related 
4810: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4820: 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78 2e  ode as a prefix.
4830: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d 20  .**.** {F10224} 
4840: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  Primary result c
4850: 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69  ode names contai
4860: 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63  n a single "_" c
4870: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  haracter..**.** 
4880: 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65  {F10225} Extende
4890: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  d result code na
48a0: 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20  mes contain two 
48b0: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72  or more "_" char
48c0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  acters..**.** {F
48d0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72  10226} The numer
48e0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65  ic value of an e
48f0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4900: 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ode contains the
4910: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
4920: 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74  eric value of it
4930: 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  s corresponding 
4940: 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  primary result c
4950: 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ode in.**       
4960: 20 20 20 69 74 73 20 6c 65 61 73 74 20 73 69 67     its least sig
4970: 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e  nificant 8 bits.
4980: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
4990: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
49a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
49b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
49c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
49d0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
49e0: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
49f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
4a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4a10: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
4a20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4a30: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
4a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a50: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
4a60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4a70: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
4a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4a90: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
4aa0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4ab0: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
4ac0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ad0: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
4ae0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4af0: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
4b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4b10: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
4b20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4b30: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
4b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4b50: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
4b60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b70: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
4b80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b90: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
4ba0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4bb0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
4bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4bd0: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
4be0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4bf0: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
4c00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c10: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
4c20: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c30: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
4c40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c50: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
4c60: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c70: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
4c80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c90: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
4ca0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cb0: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
4cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4cd0: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
4ce0: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
4cf0: 7c 20 28 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a  | (14<<8))../*.*
4d00: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
4d10: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
4d20: 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30 32  Operations {F102
4d30: 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  30}.**.** These 
4d40: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
4d50: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
4d60: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
4d70: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
4d80: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
4d90: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
4da0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
4db0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4dc0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
4dd0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4de0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  vfs] object..*/.
4df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e00: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
4e10: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
4e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e30: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
4e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
4e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e60: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
4e70: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
4e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4e90: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
4ea0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a  E    0x00000008.
4eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ec0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
4ed0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
4ee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4ef0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
4f00: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
4f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f20: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
4f30: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
4f40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f50: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
4f60: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4f80: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
4f90: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a       0x00000800.
4fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4fb0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
4fc0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a       0x00001000.
4fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4fe0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
4ff0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
5000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5010: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
5020: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a  AL   0x00004000.
5030: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5040: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5050: 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30 7d  ristics {F10240}
5060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
5070: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d  ceCapabilities m
5080: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5090: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
50a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
50b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
50c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
50d0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
50e0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
50f0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5100: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5110: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5120: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5130: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5140: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5150: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5160: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5170: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5180: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5190: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
51a0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
51b0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
51c0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
51d0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
51e0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
51f0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5200: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5210: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5220: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5230: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5240: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5250: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5260: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5270: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5280: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5290: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
52a0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
52b0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
52c0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
52d0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
52e0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
52f0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5300: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5310: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5320: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5330: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5340: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5350: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5360: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5370: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5380: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5390: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
53a0: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  te()..*/.#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53c0: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78  OMIC          0x
53d0: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
53e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
53f0: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78  OMIC512       0x
5400: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
5410: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5420: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78  OMIC1K        0x
5430: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5450: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78  OMIC2K        0x
5460: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5480: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78  OMIC4K        0x
5490: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
54a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
54b0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78  OMIC8K        0x
54c0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
54d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
54e0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78  OMIC16K       0x
54f0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5510: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78  OMIC32K       0x
5520: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5540: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78  OMIC64K       0x
5550: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5560: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5570: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78  FE_APPEND     0x
5580: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5590: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
55a0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78  QUENTIAL      0x
55b0: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20  00000400../*.** 
55c0: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
55d0: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 46  ocking Levels {F
55e0: 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  10250}.**.** SQL
55f0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
5600: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5610: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5620: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
5630: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
5640: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
5650: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
5660: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
5670: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5680: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
5690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
56a0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
56b0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
56c0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
56d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
56e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
56f0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
5700: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
5710: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
5720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5730: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
5740: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
5750: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
5760: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
5770: 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57 68  F10260}.**.** Wh
5780: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5790: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
57a0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
57b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
57c0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
57d0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
57e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
57f0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5800: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5810: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5820: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5830: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5840: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5850: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5860: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5870: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5880: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5890: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
58a0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
58b0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68  t be flushed. Th
58c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
58d0: 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 20  RMAL flag means 
58e0: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
58f0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
5900: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
5910: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
5920: 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65 20  eans .** to use 
5930: 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66  Mac OS-X style f
5940: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
5950: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23  of fsync()..*/.#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
5970: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
5980: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
5990: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
59a0: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
59b0: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
59c0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
59d0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 0a 2f       0x00010.../
59e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
59f0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5a00: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31   File Handle {F1
5a10: 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  1110}.**.** An [
5a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
5a30: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
5a40: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
5a50: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
5a60: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
5a70: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
5a80: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
5a90: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
5aa0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
5ab0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
5ac0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
5ad0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
5ae0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
5af0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
5b00: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
5b10: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
5b40: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
5b50: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
5b60: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
5b70: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
5b80: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
5b90: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
5ba0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
5bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
5bc0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
5bd0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5be0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
5bf0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
5c00: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
5c10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
5c30: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
5c40: 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30  s Object {F11120
5c50: 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  }.**.** Every fi
5c60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
5c70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
5c80: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74  Open method cont
5c90: 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ains a pointer t
5ca0: 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65  o.** an instance
5cb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
5cc0: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65    This object de
5cd0: 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74  fines the.** met
5ce0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
5cf0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
5d00: 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20  rations against 
5d10: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
5d20: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
5d30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
5d40: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
5d50: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5d60: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
5d70: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
5d80: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
5d90: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
5da0: 79 6e 63 28 29 2e 0a 2a 20 20 54 68 65 20 73 65  ync()..*  The se
5db0: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
5dc0: 6e 0a 2a 2a 20 4f 53 2d 58 20 73 74 79 6c 65 20  n.** OS-X style 
5dd0: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 53  fullsync.  The S
5de0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 20  QLITE_SYNC_DATA 
5df0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
5e00: 20 69 6e 20 74 6f 0a 2a 2a 20 69 6e 64 69 63 61   in to.** indica
5e10: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
5e20: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
5e30: 65 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  e and not its in
5e40: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 0a  ode needs to be.
5e50: 2a 2a 20 73 79 6e 63 65 64 2e 0a 2a 2a 20 0a 2a  ** synced..** .*
5e60: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
5e70: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
5e80: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
5e90: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
5ea0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5eb0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
5ec0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5ed0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
5ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5ef0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
5f00: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
5f10: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
5f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
5f30: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
5f40: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
5f50: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
5f60: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
5f70: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
5f80: 63 6b 2e 20 20 0a 2a 2a 20 54 68 65 20 78 43 68  ck.  .** The xCh
5f90: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
5fa0: 29 20 6d 65 74 68 6f 64 20 6c 6f 6f 6b 73 0a 2a  ) method looks.*
5fb0: 2a 20 74 6f 20 73 65 65 20 69 66 20 61 6e 79 20  * to see if any 
5fc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5fd0: 69 6f 6e 2c 20 65 69 74 68 65 72 20 69 6e 20 74  ion, either in t
5fe0: 68 69 73 0a 2a 2a 20 70 72 6f 63 65 73 73 20 6f  his.** process o
5ff0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
6000: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
6010: 69 6e 67 20 61 6e 20 52 45 53 45 52 56 45 44 2c  ing an RESERVED,
6020: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6030: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6040: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6050: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6060: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6070: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6080: 69 66 20 6e 6f 74 2e 0a 2a 2a 20 0a 2a 2a 20 54  if not..** .** T
6090: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
60a0: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
60b0: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
60c0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
60d0: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
60e0: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
60f0: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
6100: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
6110: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6120: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
6130: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
6140: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
6150: 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 61 6e 20 69  ument.** is an i
6160: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
6170: 20 54 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   The third.** ar
6180: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6190: 72 69 63 20 70 6f 69 6e 74 65 72 20 77 68 69 63  ric pointer whic
61a0: 68 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  h is intended to
61b0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   be a pointer.**
61c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
61d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
61e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
61f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
6200: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
6210: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6220: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6230: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6240: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6250: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6260: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6270: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6280: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6290: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
62a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
62b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
62c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
62d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
62e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
62f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6300: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6310: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6320: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
6330: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
6340: 6e 20 75 73 65 2e 20 0a 2a 2a 20 41 20 5b 53 51  n use. .** A [SQ
6350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6360: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6370: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6380: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6390: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
63a0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
63b0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
63c0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
63d0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 20  uld use opcodes 
63e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
63f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6400: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6410: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6420: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6430: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6440: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6450: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6460: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6470: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6480: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6490: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
64a0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
64b0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
64c0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
64d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
64e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
64f0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6500: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6510: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6520: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6530: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6540: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6550: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6560: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6570: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6580: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
6590: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
65b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
65d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
65f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6600: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6610: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6630: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6640: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6650: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6660: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6670: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6680: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6690: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
66b0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
66c0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
66d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
66e0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
66f0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6700: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6710: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6720: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6730: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6740: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6750: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6760: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6770: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6780: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6790: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
67a0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
67b0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
67c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
67d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
67e0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
67f0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6800: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6810: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6820: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6830: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6840: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6850: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6860: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6870: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6880: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6890: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
68a0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
68b0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
68c0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
68d0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
68e0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
68f0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
6900: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
6910: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
6920: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
6930: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
6940: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6950: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
6960: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
6970: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
6980: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
6990: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
69a0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
69b0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
69c0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
69d0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
69e0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
69f0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6a00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6a10: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
6a20: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
6a30: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6a40: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
6a50: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
6a60: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
6a70: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
6a80: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
6a90: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
6aa0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
6ab0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
6ac0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
6ad0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
6ae0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6af0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6b00: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
6b10: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
6b20: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
6b30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
6b40: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
6b50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
6b60: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
6b70: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
6b80: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6b90: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
6ba0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6bb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
6bc0: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
6bd0: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
6be0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6bf0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
6c00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c10: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
6c20: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
6c30: 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F11310}.**.** Th
6c40: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
6c50: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
6c60: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
6c70: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
6c80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6c90: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ca0: 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65 20 5b  ect and to the [
6cb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6cc0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6cd0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6ce0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6cf0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6d00: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6d10: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6d20: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6d30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6d40: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
6d50: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
6d60: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
6d70: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6d80: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6d90: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6da0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
6db0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
6dc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6dd0: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
6de0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
6df0: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
6e00: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
6e10: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
6e20: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
6e30: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
6e40: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
6e50: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
6e60: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
6e70: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
6e80: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
6e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ea0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
6eb0: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
6ed0: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
6ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
6ef0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
6f00: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
6f10: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
6f20: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
6f30: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
6f40: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
6f50: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
6f60: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
6f70: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
6f80: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
6f90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
6fa0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
6fb0: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
6fc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
6fd0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
6fe0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
6ff0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
7000: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
7010: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
7020: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7030: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
7040: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
7050: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7060: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
7070: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
7080: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7090: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
70a0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
70b0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
70c0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
70d0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
70e0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
70f0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7100: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7110: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7120: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7130: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7140: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7150: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
7160: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
7170: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
7180: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
7190: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
71a0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
71b0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
71c0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
71d0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
71e0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
71f0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7200: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7210: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7220: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7230: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7240: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7250: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7260: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7270: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7280: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7290: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
72a0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
72b0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
72c0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
72d0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
72e0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
72f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7300: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7310: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7320: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7330: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7340: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7350: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7360: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7370: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7380: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7390: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
73a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
73b0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
73c0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
73d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 0a 2a 2a 20  sqlite3_vfs .** 
73e0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
73f0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
7400: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
7410: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
7420: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
7430: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
7440: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
7450: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
7460: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
7470: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
7480: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
7490: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
74a0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
74b0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
74c0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
74d0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
74e0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
74f0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
7500: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
7510: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
7520: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
7530: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
7540: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34  es..**.** {F1114
7550: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
7560: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7570: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
7580: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
7590: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
75a0: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
75b0: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
75c0: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
75d0: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
75e0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
75f0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
7600: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
7610: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 7b 45 4e 44  ** called.  {END
7620: 7d 20 53 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  } So the [sqlite
7630: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 74 6f 72  3_file] can stor
7640: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
7650: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
7660: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
7670: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
7680: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
7690: 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  son..**.** {F111
76a0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
76b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
76c0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
76d0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
76e0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
76f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
7700: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
7710: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
7720: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
7730: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
7740: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
7750: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
7760: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
7770: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
7780: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
7790: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
77a0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
77b0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
77c0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
77d0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
77e0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
77f0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
7800: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
7810: 46 6c 61 67 73 20 6d 61 79 20 62 65 0a 2a 2a 20  Flags may be.** 
7820: 73 65 74 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  set..** .** {F11
7830: 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  143} SQLite will
7840: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
7850: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
7860: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
7870: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
7880: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
7890: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
78a0: 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  d:.** .** <ul>.*
78b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
78c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
78d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
78e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
78f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7900: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
7910: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7920: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
7930: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
7940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
7950: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
7960: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
7970: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
7980: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7990: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
79a0: 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
79b0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
79c0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
79d0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
79e0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
79f0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 68  to.** changes th
7a00: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7a10: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7a20: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7a30: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7a40: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
7a50: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
7a60: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
7a70: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
7a80: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
7a90: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
7aa0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
7ab0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7ac0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7ad0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7ae0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7af0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7b00: 72 6e 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  rn .** SQLITE_IO
7b10: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7b20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7b30: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7b40: 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
7b50: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
7b60: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
7b70: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
7b80: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
7b90: 64 6f 6d 20 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  dom .** order an
7ba0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
7bb0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
7bc0: 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a 2a 2a 20 53  dingly..** .** S
7bd0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
7be0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
7bf0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
7c00: 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
7c10: 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  method:.** .** <
7c20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7c30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7c40: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
7c50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
7c60: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
7c70: 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 35 7d  .** .** {F11145}
7c80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7c90: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7ca0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
7cb0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
7cc0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
7cd0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46  t is closed.  {F
7ce0: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
7cf0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
7d00: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
7d10: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
7d20: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
7d30: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
7d40: 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a 20 7b 46 31  ournals. .** {F1
7d50: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
7d60: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
7d70: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
7d80: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
7d90: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
7da0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
7db0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
7dc0: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
7dd0: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
7de0: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
7df0: 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a  file. {END}.** .
7e00: 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c  ** {F11148} At l
7e10: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
7e20: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
7e30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
7e40: 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20 68 6f 6c  QLite .** to hol
7e50: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
7e60: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
7e70: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
7e80: 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ird .** argument
7e90: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b 45 4e 44   to xOpen.  {END
7ea0: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
7eb0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
7ec0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
7ed0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
7ee0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
7ef0: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 20 0a 2a  ill it in..** .*
7f00: 2a 20 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66  * {F11149} The f
7f10: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7f20: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
7f30: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
7f40: 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20  _EXISTS] .** to 
7f50: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
7f60: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
7f70: 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
7f80: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
7f90: 5d 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65  ] to test to see
7fa0: 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65 20 69 73  .** if a file is
7fb0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
7fc0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
7fd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
7fe0: 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f 20 73 65  ** to test to se
7ff0: 65 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 61  e if a file is a
8000: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
8010: 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c  .  {END} The fil
8020: 65 20 63 61 6e 20 62 65 20 61 20 0a 2a 2a 20 64  e can be a .** d
8030: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 0a 2a 2a  irectory..** .**
8040: 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74 65   {F11150} SQLite
8050: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8060: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8070: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
8080: 73 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74  s for.** the out
8090: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
80a0: 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35  Pathname. {F1115
80b0: 31 7d 20 54 68 65 20 65 78 61 63 74 0a 2a 2a 20  1} The exact.** 
80c0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
80d0: 75 74 20 62 75 66 66 65 72 20 69 73 20 61 6c 73  ut buffer is als
80e0: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
80f0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
8100: 0a 2a 2a 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e  .** methods. {EN
8110: 44 7d 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  D} If the output
8120: 20 62 75 66 66 65 72 20 69 73 20 6e 6f 74 20 6c   buffer is not l
8130: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8140: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 0a 2a  LITE_CANTOPEN].*
8150: 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
8160: 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20 69 73  rned. As this is
8170: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
8180: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
8190: 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d 70 6c  ite,.** vfs impl
81a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
81b0: 6c 64 20 65 6e 64 65 61 76 6f 72 20 74 6f 20 70  ld endeavor to p
81c0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
81d0: 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50 61 74  etting .** mxPat
81e0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
81f0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
8200: 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  lue..** .** The 
8210: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
8220: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
8230: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
8240: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8250: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8260: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8270: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8280: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
8290: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
82a0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
82b0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
82c0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
82d0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
82e0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
82f0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
8300: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
8310: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
8320: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
8330: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
8340: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8350: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8360: 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 78  ained.  The.** x
8370: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
8380: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
8390: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
83a0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
83b0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
83c0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
83d0: 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e  en.  The xCurren
83e0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
83f0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
8400: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
8410: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
8420: 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e 0a  te and.** time..
8430: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
8440: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
8450: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
8460: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
8470: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
8480: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
8490: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
84a0: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
84b0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
84c0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
84d0: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
84e0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
84f0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
8500: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
8510: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
8520: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
8530: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
8540: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
8550: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
8560: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8570: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
8580: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
8590: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
85a0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
85b0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
85c0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
85d0: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
85e0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
85f0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8600: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
8610: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
8620: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
8630: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
8640: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
8650: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
8660: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8670: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8680: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
8690: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
86a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
86b0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
86c0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
86d0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86e0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
86f0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8700: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
8710: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
8720: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
8730: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
8740: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8750: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
8760: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
8770: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
8780: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
8790: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
87a0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
87b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
87c0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
87d0: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
87e0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
87f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
8800: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
8810: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
8820: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
8830: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
8840: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
8850: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
8860: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
8870: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
8880: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
8890: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
88a0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
88b0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
88c0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
88d0: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
88e0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
88f0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
8900: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
8910: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
8920: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
8930: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
8940: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
8950: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
8960: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
8970: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31  s VFS method {F1
8980: 31 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  1190}.**.** {F11
8990: 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67  191} These integ
89a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
89b0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
89c0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
89d0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
89e0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
89f0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
8a00: 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79  ect. {END}  They
8a10: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
8a20: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
8a30: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
8a40: 73 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20  ss method is.** 
8a50: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 7b 46  looking for.  {F
8a60: 31 31 31 39 32 7d 20 57 69 74 68 20 5b 53 51 4c  11192} With [SQL
8a70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
8a80: 53 5d 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  S], the xAccess 
8a90: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
8aa0: 20 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69   checks to see i
8ab0: 66 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  f the file exist
8ac0: 73 2e 20 7b 46 31 31 31 39 33 7d 20 57 69 74 68  s. {F11193} With
8ad0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45 53  .** SQLITE_ACCES
8ae0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8af0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8b00: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 0a 2a 2a  checks to see.**
8b10: 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
8b20: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
8b30: 64 20 77 72 69 74 61 62 6c 65 2e 20 20 7b 46 31  d writable.  {F1
8b40: 31 31 39 34 7d 20 57 69 74 68 0a 2a 2a 20 53 51  1194} With.** SQ
8b50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8b60: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
8b70: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
8b80: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
8b90: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
8ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8bb0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
8bc0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
8bd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8be0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
8bf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
8c00: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
8c10: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
8c20: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
8c30: 62 72 61 72 79 20 7b 46 31 30 31 33 30 7d 0a 2a  brary {F10130}.*
8c40: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
8c50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
8c60: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
8c70: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
8c80: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
8c90: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
8ca0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
8cb0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
8cc0: 6f 77 6e 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  own().** routine
8cd0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
8ce0: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ct of sqlite3_in
8cf0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 54 79 70  itialize().  Typ
8d00: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
8d10: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
8d20: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
8d30: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
8d40: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
8d50: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
8d60: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
8d70: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
8d80: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
8d90: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
8da0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
8db0: 56 46 53 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  VFS] module, or 
8dc0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
8dd0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
8de0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
8df0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
8e00: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
8e10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
8e20: 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
8e30: 6c 6c 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  lled multiple ti
8e40: 6d 65 73 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  mes.** without c
8e50: 6f 6e 73 65 71 75 65 6e 63 65 2e 20 20 53 65 63  onsequence.  Sec
8e60: 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
8e70: 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 73 20 6f  nt evaluations o
8e80: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  f.** sqlite3_ini
8e90: 74 69 61 6c 69 7a 65 28 29 20 61 72 65 20 6e 6f  tialize() are no
8ea0: 2d 6f 70 73 2e 20 20 54 68 65 20 73 71 6c 69 74  -ops.  The sqlit
8eb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
8ec0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 6f 6e 6c 79 20  routine.** only 
8ed0: 77 6f 72 6b 73 20 74 68 65 20 66 69 72 73 74 20  works the first 
8ee0: 74 69 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65  time it is calle
8ef0: 64 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 2c  d for a process,
8f00: 20 6f 72 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   or the first.**
8f10: 20 74 69 6d 65 20 69 74 20 69 73 20 63 61 6c 6c   time it is call
8f20: 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
8f30: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 49 6e  _shutdown().  In
8f40: 20 61 6c 6c 20 6f 74 68 65 72 20 63 61 73 65 73   all other cases
8f50: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  ,.** sqlite3_ini
8f60: 74 69 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  tialize() return
8f70: 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a  s SQLITE_OK..**.
8f80: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
8f90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
8fa0: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
8fb0: 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73  TE_OK on success
8fc0: 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65  ..** If for some
8fd0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
8fe0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8ff0: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
9000: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
9010: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
9020: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
9030: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
9040: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
9050: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
9060: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
9070: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
9080: 61 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  an SQLITE_OK..**
9090: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
90a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
90b0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
90c0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
90d0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
90e0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
90f0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
9100: 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 74 79 70  ion does not typ
9110: 69 63 61 6c 6c 79 20 6e 65 65 64 20 74 6f 0a 2a  ically need to.*
9120: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
9130: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
9140: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
9150: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
9160: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
9170: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9180: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
9190: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
91a0: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
91b0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
91c0: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
91d0: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
91e0: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
91f0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
9200: 61 6c 72 65 61 64 79 2e 0a 2a 2a 0a 2a 2a 20 41  already..**.** A
9210: 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65  ppropriate imple
9220: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
9230: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9240: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
9250: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 61 72  shutdown().** ar
9260: 65 20 70 72 6f 76 69 64 65 64 20 61 73 20 70 61  e provided as pa
9270: 72 74 20 6f 66 20 53 51 4c 69 74 65 20 77 68 65  rt of SQLite whe
9280: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
9290: 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 33 32   for unix, win32
92a0: 2c 20 61 6e 64 0a 2a 2a 20 6f 73 2f 32 2e 20 20  , and.** os/2.  
92b0: 48 6f 77 65 76 65 72 2c 20 77 68 65 6e 20 53 51  However, when SQ
92c0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
92d0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
92e0: 6f 72 6d 73 2c 20 74 68 65 0a 2a 2a 20 69 6d 70  orms, the.** imp
92f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
9300: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9310: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
9320: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 0a  _shutdown() are.
9330: 2a 2a 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 6d  ** omitted and m
9340: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
9350: 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
9360: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d  on..**.** The im
9370: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
9380: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9390: 69 7a 65 28 29 20 66 6f 72 20 75 6e 69 78 2c 20  ize() for unix, 
93a0: 77 69 6e 33 32 2c 20 61 6e 64 20 6f 73 2f 32 0a  win32, and os/2.
93b0: 2a 2a 20 61 72 65 20 74 68 72 65 61 64 73 61 66  ** are threadsaf
93c0: 65 20 61 6e 64 20 6e 65 76 65 72 20 66 61 69 6c  e and never fail
93d0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  .  However, the 
93e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
93f0: 7a 65 28 29 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  ze().** implemen
9400: 74 61 74 69 6f 6e 20 66 6f 72 20 6f 74 68 65 72  tation for other
9410: 20 6f 70 65 72 61 74 69 6f 6e 69 6e 67 20 73 79   operationing sy
9420: 73 74 65 6d 73 20 6d 69 67 68 74 20 6e 6f 74 20  stems might not 
9430: 62 65 20 74 68 72 65 61 64 73 61 66 65 0a 2a 2a  be threadsafe.**
9440: 20 61 6e 64 20 73 6f 20 70 6f 72 74 61 62 6c 65   and so portable
9450: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61   applications ma
9460: 79 20 77 61 6e 74 20 74 6f 20 69 6e 76 6f 6b 65  y want to invoke
9470: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9480: 69 7a 65 28 29 0a 2a 2a 20 61 74 20 61 70 70 6c  ize().** at appl
9490: 69 63 61 74 69 6f 6e 20 73 74 61 72 74 75 70 20  ication startup 
94a0: 62 65 66 6f 72 65 20 6f 74 68 65 72 20 74 68 72  before other thr
94b0: 65 61 64 73 20 61 72 65 20 63 72 65 61 74 65 64  eads are created
94c0: 20 61 6e 64 20 63 68 65 63 6b 0a 2a 2a 20 74 68   and check.** th
94d0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 74 6f  e return code to
94e0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20   make sure that 
94f0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 77  initialization w
9500: 61 73 20 73 75 63 63 65 73 73 66 75 6c 20 62 65  as successful be
9510: 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
9520: 6e 67 2e 20 20 54 6f 20 72 65 73 74 61 74 65 3a  ng.  To restate:
9530: 20 69 74 20 69 73 20 6e 65 76 65 72 20 6e 65 63   it is never nec
9540: 65 73 73 61 72 79 20 74 6f 20 63 61 6c 6c 20 73  essary to call s
9550: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9560: 65 28 29 0a 2a 2a 20 6f 6e 20 75 6e 69 78 2c 20  e().** on unix, 
9570: 77 69 6e 33 32 2c 20 6f 72 20 6f 73 2f 32 2c 20  win32, or os/2, 
9580: 62 75 74 20 6d 61 6b 69 6e 67 20 61 20 73 65 72  but making a ser
9590: 69 61 6c 69 7a 65 64 20 63 61 6c 6c 20 74 6f 0a  ialized call to.
95a0: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
95b0: 61 6c 69 7a 65 28 29 20 6d 69 67 68 74 20 62 65  alize() might be
95c0: 20 6e 65 63 65 73 73 61 72 79 20 6f 6e 20 6f 74   necessary on ot
95d0: 68 65 72 20 6f 70 65 72 61 74 69 6e 67 20 73 79  her operating sy
95e0: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stems..**.** The
95f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9600: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  n() interface is
9610: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 20   not threadsafe 
9620: 6f 6e 20 61 6e 79 20 70 6c 61 74 66 6f 72 6d 20  on any platform 
9630: 61 6e 64 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  and.** should be
9640: 20 73 65 72 69 61 6c 69 7a 65 64 20 62 79 20 74   serialized by t
9650: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
9660: 20 46 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   Few application
9670: 73 20 73 68 6f 75 6c 64 20 65 76 65 72 0a 2a 2a  s should ever.**
9680: 20 6e 65 65 64 20 74 6f 20 63 61 6c 6c 20 73 71   need to call sq
9690: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
96a0: 2e 20 20 41 62 6f 75 74 20 74 68 65 20 6f 6e 6c  .  About the onl
96b0: 79 20 72 65 61 73 6f 6e 20 66 6f 72 20 63 61 6c  y reason for cal
96c0: 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
96d0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 74 6f  shutdown() is to
96e0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 73 74 61 74   deallocate stat
96f0: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
9700: 74 69 6f 6e 73 20 74 6f 20 73 75 70 70 72 65 73  tions to suppres
9710: 73 0a 2a 2a 20 73 70 75 72 69 6f 75 73 20 72 65  s.** spurious re
9720: 70 6f 72 74 73 20 6f 66 20 6d 65 6d 6f 72 79 20  ports of memory 
9730: 6c 65 61 6b 73 20 66 72 6f 6d 20 70 72 6f 67 72  leaks from progr
9740: 61 6d 20 61 6e 61 6c 79 73 69 73 20 74 6f 6f 6c  am analysis tool
9750: 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
9760: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
9770: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
9780: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
9790: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
97a0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
97b0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
97c0: 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a 20 54  {F10145}.**.** T
97d0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
97e0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
97f0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
9800: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
9810: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
9820: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
9830: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
9840: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
9850: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
9860: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
9870: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
9880: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
9890: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
98a0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
98b0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
98c0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
98d0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
98e0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
98f0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
9900: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
9910: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
9920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9930: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
9940: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
9950: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
9960: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
9970: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
9980: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
9990: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
99a0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
99b0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
99c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
99d0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
99e0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
99f0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
9a00: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
9a10: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
9a20: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
9a30: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
9a40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9a50: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
9a60: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
9a70: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
9a80: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
9a90: 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  that sqlite3_con
9aa0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
9ab0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
9ac0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
9ad0: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
9ae0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
9af0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9b00: 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ze()]..**.** The
9b10: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
9b20: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
9b30: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
9b40: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
9b50: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
9b60: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
9b70: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
9b80: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
9b90: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
9ba0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
9bb0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
9bc0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
9bd0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
9be0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
9bf0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
9c00: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
9c10: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
9c20: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
9c30: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
9c40: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
9c50: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
9c60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
9c70: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9c80: 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  OK..** If the op
9c90: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
9ca0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
9cb0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
9cc0: 70 74 69 6f 6e 20 28 66 6f 72 0a 2a 2a 20 65 78  ption (for.** ex
9cd0: 61 6d 70 6c 65 20 69 66 20 6f 6e 65 20 61 74 74  ample if one att
9ce0: 65 6d 70 74 73 20 74 6f 20 73 65 74 20 61 20 74  empts to set a t
9cf0: 68 72 65 61 64 73 61 66 65 20 6f 70 74 69 6f 6e  hreadsafe option
9d00: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 0a   when SQLite is.
9d10: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
9d20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
9d30: 46 45 3d 30 20 61 6e 64 20 69 73 20 74 68 75 73  FE=0 and is thus
9d40: 20 69 6e 63 61 70 61 62 6c 65 20 6f 66 20 62 65   incapable of be
9d50: 69 6e 67 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ing.** threadsaf
9d60: 65 29 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  e) then this rou
9d70: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
9d80: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
9d90: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
9da0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
9db0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
9dc0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
9dd0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 46  ation Options {F
9de0: 31 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10160}.**.** The
9df0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
9e00: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
9e10: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
9e20: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
9e30: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
9e40: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
9e50: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
9e60: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
9e70: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
9e80: 20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74   .** <dl>.** <dt
9e90: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
9ea0: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
9eb0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
9ec0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
9ed0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
9ee0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
9ef0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
9f00: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
9f10: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
9f20: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
9f30: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
9f40: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
9f50: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
9f60: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
9f70: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
9f80: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
9f90: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
9fa0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
9fb0: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
9fc0: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
9fd0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
9fe0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
9ff0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a000: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
a010: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
a020: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
a030: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
a040: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
a050: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
a060: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
a070: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
a080: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
a090: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
a0a0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
a0b0: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
a0c0: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
a0d0: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
a0e0: 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
a0f0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
a100: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
a110: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
a120: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
a130: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
a140: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   This option ena
a150: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
a160: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
a170: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
a180: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
a190: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
a1a0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
a1b0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
a1c0: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
a1d0: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
a1e0: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
a1f0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
a200: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
a210: 48 52 45 41 44 53 41 46 45 3d 31 29 20 74 68 65  HREADSAFE=1) the
a220: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
a230: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
a240: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
a250: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
a260: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
a270: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a280: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
a290: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
a2a0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
a2b0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
a2c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
a2d0: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
a2e0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
a2f0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
a300: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
a310: 65 20 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e time.</dd>.**.
a320: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
a330: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
a340: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
a350: 69 6f 6e 20 74 61 6b 65 73 20 66 6f 75 72 20 61  ion takes four a
a360: 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 66  rguments.  The f
a370: 69 72 73 74 20 74 68 72 65 65 0a 2a 2a 20 61 72  irst three.** ar
a380: 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
a390: 74 65 72 73 20 74 6f 20 66 75 6e 63 74 69 6f 6e  ters to function
a3a0: 73 20 74 68 61 74 20 65 6d 75 6c 61 74 65 20 6d  s that emulate m
a3b0: 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c  alloc(), free(),
a3c0: 0a 2a 2a 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28  .** and realloc(
a3d0: 29 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ), respectively.
a3e0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67    The fourth arg
a3f0: 75 6d 65 6e 74 20 69 73 20 65 69 74 68 65 72 20  ument is either 
a400: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
a410: 61 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  a function that 
a420: 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
a430: 20 6f 66 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f   of a prior allo
a440: 63 61 74 69 6f 6e 2c 20 6f 72 20 4e 55 4c 4c 2e  cation, or NULL.
a450: 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 6f 75 72    If.** the four
a460: 74 68 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  th function is N
a470: 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
a480: 20 6b 65 65 70 20 74 72 61 63 6b 20 6f 66 20 61   keep track of a
a490: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 73 69 7a  llocation.** siz
a4a0: 65 73 20 69 74 73 65 6c 66 2e 20 20 54 68 69 73  es itself.  This
a4b0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
a4c0: 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 64  to replace the d
a4d0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 0a 2a 2a  efault memory.**
a4e0: 20 61 6c 6c 6f 63 61 74 6f 72 20 77 69 74 68 20   allocator with 
a4f0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
a500: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
a510: 6c 6f 63 61 74 6f 72 2e 3c 2f 64 64 3e 0a 2a 2a  locator.</dd>.**
a520: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
a530: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 53 3c 2f  ONFIG_MEMSTATS</
a540: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
a550: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
a560: 67 6c 65 20 62 6f 6f 6c 65 61 6e 20 61 72 67 75  gle boolean argu
a570: 6d 65 6e 74 20 77 68 69 63 68 20 65 6e 61 62 6c  ment which enabl
a580: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 0a 2a  es or disables.*
a590: 2a 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  * the collection
a5a0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
a5b0: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
a5c0: 2e 20 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  .  When disabled
a5d0: 2c 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  , the.** followi
a5e0: 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
a5f0: 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
a600: 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
a610: 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
a620: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
a630: 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
a640: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
a650: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
a660: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
a670: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
a680: 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  it()].**   </ul>
a690: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  .** </dd>.** </d
a6a0: 6c 3e 0a 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  l>.*/ .#define S
a6b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
a6c0: 47 4c 45 54 48 52 45 41 44 20 20 20 20 20 20 20  GLETHREAD       
a6d0: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
a6e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
a6f0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
a700: 20 20 20 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20        2  /* nil 
a710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a720: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
a730: 5a 45 44 20 20 20 20 20 20 20 20 20 33 20 20 2f  ZED         3  /
a740: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
a750: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
a760: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 20  ALLOC           
a770: 20 20 34 20 20 2f 2a 20 6d 61 6c 6c 6f 63 2c 20    4  /* malloc, 
a780: 66 72 65 65 2c 20 72 65 61 6c 6c 6f 63 2c 20 6d  free, realloc, m
a790: 65 6d 73 69 7a 65 20 2a 2f 0a 23 64 65 66 69 6e  emsize */.#defin
a7a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
a7b0: 4d 45 4d 53 54 41 54 53 20 20 20 20 20 20 20 20  MEMSTATS        
a7c0: 20 20 20 35 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     5  /* boolean
a7d0: 20 2a 2f 0a 0a 2f 2a 20 54 68 65 73 65 20 6f 70   */../* These op
a7e0: 74 69 6f 6e 73 20 61 72 65 20 74 6f 20 62 65 20  tions are to be 
a7f0: 61 64 64 65 64 20 6c 61 74 65 72 2e 20 20 43 75  added later.  Cu
a800: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 20 61  rrently unused a
a810: 6e 64 20 75 6e 64 6f 63 75 6d 65 6e 74 65 64 2e  nd undocumented.
a820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a830: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 4d 41  TE_CONFIG_PAGEMA
a840: 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 36 20 20  LLOC         6  
a850: 2f 2a 20 6d 61 6c 6c 6f 63 2c 20 66 72 65 65 20  /* malloc, free 
a860: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a870: 45 5f 43 4f 4e 46 49 47 5f 54 45 4d 50 4d 41 4c  E_CONFIG_TEMPMAL
a880: 4c 4f 43 20 20 20 20 20 20 20 20 20 37 20 20 2f  LOC         7  /
a890: 2a 20 6d 61 6c 6c 6f 63 2c 20 66 72 65 65 20 2a  * malloc, free *
a8a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
a8b0: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
a8c0: 20 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a             8  /*
a8d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 36 34 20 2a 2f   void*, int64 */
a8e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a8f0: 43 4f 4e 46 49 47 5f 50 41 47 45 48 45 41 50 20  CONFIG_PAGEHEAP 
a900: 20 20 20 20 20 20 20 20 20 20 39 20 20 2f 2a 20            9  /* 
a910: 76 6f 69 64 2a 2c 20 69 6e 74 36 34 20 2a 2f 0a  void*, int64 */.
a920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a930: 4f 4e 46 49 47 5f 54 45 4d 50 48 45 41 50 20 20  ONFIG_TEMPHEAP  
a940: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 76          10  /* v
a950: 6f 69 64 2a 2c 20 69 6e 74 36 34 20 2a 2f 0a 0a  oid*, int64 */..
a960: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a970: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
a980: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
a990: 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30 30  lt Codes {F12200
a9a0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
a9b0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
a9c0: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
a9d0: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
a9e0: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
a9f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
aa00: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
aa10: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
aa20: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  re of SQLite..**
aa30: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
aa40: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 64  sult codes are d
aa50: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
aa60: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
aa70: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
aa80: 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ty..**.** INVARI
aa90: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
aaa0: 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64  201} Each new [d
aab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
aac0: 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74  on] shall have t
aad0: 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
aae0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
aaf0: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 0a   codes] feature.
ab00: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 73 61  **          disa
ab10: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
ab20: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20  .**.** {F12202} 
ab30: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
ab40: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
ab50: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
ab60: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a  ce shall enable.
ab70: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
ab80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
ab90: 65 73 5d 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20  es] for the .** 
aba0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
abb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
abc0: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
abd0: 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
abe0: 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61  is true, or disa
abf0: 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73  ble them if F is
ac00: 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73   false..*/.int s
ac10: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
ac20: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
ac30: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
ac40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
ac50: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
ac60: 52 6f 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a  Rowid {F12220}.*
ac70: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20  *.** Each entry 
ac80: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
ac90: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
aca0: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
acb0: 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
acc0: 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e  led the "rowid".
acd0: 20 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c   The rowid is al
ace0: 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
acf0: 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
ad00: 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
ad10: 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
ad20: 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
ad30: 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
ad40: 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
ad50: 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
ad60: 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
ad70: 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  s. If.** the tab
ad80: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
ad90: 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45 52 20  of type INTEGER 
ada0: 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e  PRIMARY KEY then
adb0: 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
adc0: 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
add0: 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
ade0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
adf0: 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 72  ne returns the r
ae00: 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74  owid of the most
ae10: 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
ae20: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74  ssful INSERT int
ae30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
ae40: 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65  rom the database
ae50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 73   connection.** s
ae60: 68 6f 77 6e 20 69 6e 20 74 68 65 20 66 69 72 73  hown in the firs
ae70: 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  t argument.  If 
ae80: 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e  no successful in
ae90: 73 65 72 74 73 0a 2a 2a 20 68 61 76 65 20 65 76  serts.** have ev
aea0: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
aeb0: 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
aec0: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
aed0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
aee0: 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63   If an INSERT oc
aef0: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
af00: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
af10: 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20  rowid of the.** 
af20: 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69 73 20  inserted row is 
af30: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
af40: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67   routine as long
af50: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 0a   as the trigger.
af60: 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  ** is running.  
af70: 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
af80: 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c  gger terminates,
af90: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
afa0: 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ned.** by this r
afb0: 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
afc0: 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65  o the last value
afd0: 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65   inserted before
afe0: 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65 72 20   the.** trigger 
aff0: 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  fired..**.** An 
b000: 49 4e 53 45 52 54 20 74 68 61 74 20 66 61 69 6c  INSERT that fail
b010: 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
b020: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
b030: 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
b040: 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 61 6e  essful insert an
b050: 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
b060: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
b070: 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
b080: 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49  routine.  Thus I
b090: 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
b0a0: 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
b0b0: 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
b0c0: 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
b0d0: 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
b0e0: 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
b0f0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
b100: 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
b110: 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
b120: 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
b130: 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
b140: 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e 63 6f 75  EPLACE .** encou
b150: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
b160: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
b170: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
b180: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
b190: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
b1a0: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
b1b0: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
b1c0: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
b1d0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
b1e0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
b1f0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
b200: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
b210: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
b220: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 20  this interface. 
b230: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
b240: 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
b250: 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69 6e 73 65  routine, an inse
b260: 72 74 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  rt is considered
b270: 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
b280: 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
b290: 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
b2a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
b2b0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
b2c0: 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20 54 68  *.** {F12221} Th
b2d0: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
b2e0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
b2f0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
b300: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
b310: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f   rowid of the mo
b320: 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
b330: 73 66 75 6c 20 69 6e 73 65 72 74 20 64 6f 6e 65  sful insert done
b340: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
b350: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
b360: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  e connection and
b370: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
b380: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
b390: 68 69 67 68 65 72 20 6c 65 76 65 6c 20 74 72 69  higher level tri
b3a0: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
b3b0: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
b3c0: 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
b3d0: 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69  been no qualifyi
b3e0: 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a  ng inserts..**.*
b3f0: 2a 20 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b  * {F12223} The [
b400: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
b410: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
b420: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a  ction returns.**
b430: 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76            same v
b440: 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64  alue when called
b450: 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
b460: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a  rigger context.*
b470: 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64  *          immed
b480: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e  iately before an
b490: 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41  d after a ROLLBA
b4a0: 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  CK..**.** LIMITA
b4b0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
b4c0: 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72  2232} If a separ
b4d0: 61 74 65 20 74 68 72 65 61 64 20 64 6f 65 73 20  ate thread does 
b4e0: 61 20 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20  a new insert on 
b4f0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
b500: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
b510: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
b520: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
b530: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
b540: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
b550: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
b560: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
b570: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
b580: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
b590: 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
b5a0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
b5b0: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
b5c0: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
b5d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
b5e0: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
b5f0: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
b600: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
b610: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
b620: 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
b630: 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
b640: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
b650: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
b660: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
b670: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b680: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
b690: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
b6a0: 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F12240}.**.** 
b6b0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
b6c0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
b6d0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
b6e0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
b6f0: 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
b700: 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
b710: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
b720: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
b730: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
b740: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
b750: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
b760: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
b770: 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67  .  Only.** chang
b780: 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
b790: 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
b7a0: 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
b7b0: 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45  DATE, or.** DELE
b7c0: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
b7d0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
b7e0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
b7f0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
b800: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
b810: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
b820: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
b830: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
b840: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
b850: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
b860: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
b870: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
b880: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
b890: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
b8a0: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
b8b0: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
b8c0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
b8d0: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
b8e0: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
b8f0: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
b900: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
b910: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
b920: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
b930: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
b940: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
b950: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
b960: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
b970: 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
b980: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
b990: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
b9a0: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
b9b0: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
b9c0: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
b9d0: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
b9e0: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
b9f0: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
ba00: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
ba10: 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
ba20: 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
ba30: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
ba40: 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
ba50: 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
ba60: 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
ba70: 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
ba80: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
ba90: 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
baa0: 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
bab0: 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
bac0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
bad0: 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
bae0: 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
baf0: 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
bb00: 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
bb10: 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
bb20: 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
bb30: 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
bb40: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
bb50: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
bb60: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
bb70: 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
bb80: 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
bb90: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
bba0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
bbb0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
bbc0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
bbd0: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
bbe0: 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
bbf0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
bc00: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
bc10: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
bc20: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
bc30: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
bc40: 2a 2a 20 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65  ** So when calle
bc50: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
bc60: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
bc70: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
bc80: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
bc90: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
bca0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
bcb0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
bcc0: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
bcd0: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
bce0: 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74  op level..** Wit
bcf0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
bd00: 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 20 73  a trigger, the s
bd10: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
bd20: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61   interface.** ca
bd30: 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
bd40: 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
bd50: 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
bd60: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
bd70: 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
bd80: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
bd90: 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
bda0: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
bdb0: 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
bdc0: 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
bdd0: 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
bde0: 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
bdf0: 20 69 6e 63 6c 75 64 65 20 69 6e 20 63 68 61 6e   include in chan
be00: 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
be10: 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
be20: 63 65 20 74 68 65 79 20 68 61 76 65 20 74 68 65  ce they have the
be30: 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a  ir own context..
be40: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
be50: 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d  lements the comm
be60: 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  and "DELETE FROM
be70: 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a   table" without.
be80: 2a 2a 20 61 20 57 48 45 52 45 20 63 6c 61 75 73  ** a WHERE claus
be90: 65 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e  e by dropping an
bea0: 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65  d recreating the
beb0: 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69   table.  (This i
bec0: 73 20 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72  s much.** faster
bed0: 20 74 68 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f   than going thro
bee0: 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
bef0: 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
bf00: 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  ents from the.**
bf10: 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73   table.)  Becaus
bf20: 65 20 6f 66 20 74 68 69 73 20 6f 70 74 69 6d 69  e of this optimi
bf30: 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65  zation, the dele
bf40: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c  tions in.** "DEL
bf50: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
bf60: 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e  are not row chan
bf70: 67 65 73 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74  ges and will not
bf80: 20 62 65 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62   be counted.** b
bf90: 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  y the sqlite3_ch
bfa0: 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69  anges() or [sqli
bfb0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
bfc0: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  s()] functions..
bfd0: 2a 2a 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  ** To get an acc
bfe0: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
bff0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
c000: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
c010: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
c020: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
c030: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  stead..**.** INV
c040: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
c050: 46 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c  F12241} The [sql
c060: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
c070: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
c080: 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
c090: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
c0a0: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
c0b0: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
c0c0: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
c0d0: 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20  DATE,.**        
c0e0: 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74    or DELETE stat
c0f0: 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d  ement on the sam
c100: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c110: 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ction and.**    
c120: 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65        within the
c130: 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20   same or higher 
c140: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
c150: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
c160: 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  e have.**       
c170: 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20     not been any 
c180: 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63  qualifying row c
c190: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  hanges..**.** {F
c1a0: 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74  12243} Statement
c1b0: 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44  s of the form "D
c1c0: 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
c1d0: 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a  name" with no.**
c1e0: 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20            WHERE 
c1f0: 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75  clause shall cau
c200: 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  se subsequent ca
c210: 6c 6c 73 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20  lls to .**      
c220: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61      [sqlite3_cha
c230: 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72  nges()] to retur
c240: 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65  n zero, regardle
c250: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ss of the.**    
c260: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
c270: 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20  rows originally 
c280: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a  in the table..**
c290: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
c2a0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20  .**.** {U12252} 
c2b0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
c2c0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
c2d0: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
c2e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c2f0: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
c300: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
c310: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
c320: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
c330: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
c340: 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65          is unpre
c350: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
c360: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
c370: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
c380: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
c390: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c3a0: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
c3b0: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46  Rows Modified {F
c3c0: 31 32 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68  12260}.***.** Th
c3d0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
c3e0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
c3f0: 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
c400: 75 73 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52  used.** by INSER
c410: 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
c420: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73  ETE statements s
c430: 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
c440: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20  e handle.** was 
c450: 6f 70 65 6e 65 64 2e 20 20 54 68 65 20 63 6f 75  opened.  The cou
c460: 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  nt includes all 
c470: 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c  changes from all
c480: 20 74 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74   trigger.** cont
c490: 65 78 74 73 2e 20 20 42 75 74 20 74 68 65 20 63  exts.  But the c
c4a0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
c4b0: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
c4c0: 65 64 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ed to.** impleme
c4d0: 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  nt REPLACE const
c4e0: 72 61 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62  raints, do rollb
c4f0: 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
c500: 6f 63 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20  ocessing,.** or 
c510: 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65  DROP table proce
c520: 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68  ssing..** The ch
c530: 61 6e 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75  anges.** are cou
c540: 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  nted as soon as 
c550: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
c560: 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
c570: 20 63 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28   completed .** (
c580: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
c590: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73  nt handle is pas
c5a0: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
c5b0: 72 65 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20  reset()] or .** 
c5c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
c5d0: 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  e()])..**.** SQL
c5e0: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
c5f0: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
c600: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
c610: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52  ithout.** a WHER
c620: 45 20 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70  E clause by drop
c630: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
c640: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
c650: 28 54 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a  (This is much.**
c660: 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
c670: 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
c680: 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
c690: 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
c6a0: 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
c6b0: 20 42 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74   Because of.** t
c6c0: 68 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  his optimization
c6d0: 2c 20 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75  , the change cou
c6e0: 6e 74 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46  nt for "DELETE F
c6f0: 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20  ROM table" will 
c700: 62 65 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72  be.** zero regar
c710: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
c720: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
c730: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
c740: 61 6c 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74  ally in the.** t
c750: 61 62 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20  able. To get an 
c760: 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
c770: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
c780: 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
c790: 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
c7a0: 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
c7b0: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20   instead..**.** 
c7c0: 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
c7d0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
c7e0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
c7f0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
c800: 20 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54 68   .** {F12261} Th
c810: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
c820: 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75  _changes()] retu
c830: 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
c840: 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
c850: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
c860: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
c870: 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72  , UPDATE, and/or
c880: 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20   DELETE.**      
c890: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f      statements o
c8a0: 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
c8b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
c8c0: 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20  , in any.**     
c8d0: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
c8e0: 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20  text, since the 
c8f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c900: 69 6f 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20 20  ion was.**      
c910: 20 20 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a      created..**.
c920: 2a 2a 20 7b 46 31 32 32 36 33 7d 20 53 74 61 74  ** {F12263} Stat
c930: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
c940: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
c950: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
c960: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
c970: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
c980: 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  l not change the
c990: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
c9a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
c9b0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
c9c0: 61 6e 67 65 73 28 29 5d 0a 2a 2a 0a 2a 2a 20 4c  anges()].**.** L
c9d0: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
c9e0: 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20 61 20  * {U12264} If a 
c9f0: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
ca00: 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
ca10: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
ca20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
ca30: 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
ca40: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
ca50: 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
ca60: 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
ca70: 6c 75 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue .**         
ca80: 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
ca90: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
caa0: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
cab0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
cac0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
cad0: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
cae0: 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
caf0: 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
cb00: 20 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d 0a   Query {F12270}.
cb10: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
cb20: 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
cb30: 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
cb40: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
cb50: 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
cb60: 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
cb70: 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
cb80: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
cb90: 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
cba0: 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
cbb0: 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
cbc0: 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
cbd0: 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
cbe0: 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
cbf0: 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
cc00: 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
cc10: 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
cc20: 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
cc30: 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
cc40: 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
cc50: 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
cc60: 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
cc70: 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
cc80: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
cc90: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
cca0: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
ccb0: 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
ccc0: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
ccd0: 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
cce0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ccf0: 69 6f 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  ion that.** is c
cd00: 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
cd10: 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
cd20: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
cd30: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
cd40: 66 20 61 6e 20 53 51 4c 20 69 73 20 76 65 72 79  f an SQL is very
cd50: 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
cd60: 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
cd70: 6e 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  n sqlite3_interr
cd80: 75 70 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c  upt().** is call
cd90: 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
cda0: 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
cdb0: 70 6f 72 74 75 6e 69 74 79 20 74 6f 20 62 65 20  portunity to be 
cdc0: 69 6e 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a 20  interrupted..** 
cdd0: 49 74 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  It might continu
cde0: 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
cdf0: 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
ce00: 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
ce10: 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
ce20: 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
ce30: 49 4e 54 45 52 52 55 50 54 5d 2e 20 20 49 66 20  INTERRUPT].  If 
ce40: 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
ce50: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
ce60: 20 61 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55   an.** INSERT, U
ce70: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
ce80: 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
ce90: 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
cea0: 73 61 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65  saction, .** the
ceb0: 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
cec0: 6e 73 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  nsaction will be
ced0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
cee0: 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41  omatically..** A
cef0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
cf00: 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73  _interrupt() has
cf10: 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
cf20: 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
cf30: 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
cf40: 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69   after sqlite3_i
cf50: 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
cf60: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
cf70: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
cf80: 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  271} The [sqlite
cf90: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69  3_interrupt()] i
cfa0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f  nterface will fo
cfb0: 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a  rce all running.
cfc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
cfd0: 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
cfe0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
cff0: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
d000: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
d010: 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65      to halt afte
d020: 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20  r processing at 
d030: 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f  most one additio
d040: 6e 61 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20  nal row of.**   
d050: 20 20 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a 0a         data..**.
d060: 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20  ** {F12272} Any 
d070: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
d080: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
d090: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e  d by [sqlite3_in
d0a0: 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20  terrupt()].**   
d0b0: 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75         will retu
d0c0: 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
d0d0: 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  RUPT]..**.** LIM
d0e0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
d0f0: 7b 55 31 32 32 37 39 7d 20 49 66 20 74 68 65 20  {U12279} If the 
d100: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d110: 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
d120: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
d130: 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  upt()].**       
d140: 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68     is running th
d150: 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
d160: 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
d170: 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
d180: 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
d190: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
d1a0: 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
d1b0: 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
d1c0: 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
d1d0: 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a  e {F10510}.**.**
d1e0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
d1f0: 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
d200: 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
d210: 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
d220: 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
d230: 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
d240: 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f  seems to form co
d250: 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61  mplete a SQL sta
d260: 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
d270: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
d280: 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
d290: 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
d2a0: 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
d2b0: 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
d2c0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
d2d0: 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
d2e0: 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
d2f0: 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
d300: 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
d310: 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61  tatement.  A sta
d320: 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
d330: 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
d340: 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
d350: 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
d360: 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
d370: 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a  a fragment of a.
d380: 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ** CREATE TRIGGE
d390: 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65  R statement.  Se
d3a0: 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
d3b0: 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
d3c0: 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
d3d0: 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
d3e0: 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
d3f0: 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
d400: 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
d410: 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
d420: 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
d430: 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
d440: 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
d450: 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
d460: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
d470: 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
d480: 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ator..**.** Thes
d490: 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
d4a0: 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
d4b0: 61 6e 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e  and.** so will n
d4c0: 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
d4d0: 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
d4e0: 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t SQL..**.** INV
d4f0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
d500: 46 31 30 35 31 31 7d 20 54 68 65 20 73 71 6c 69  F10511} The sqli
d510: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61  te3_complete() a
d520: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nd sqlite3_compl
d530: 65 74 65 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ete16() function
d540: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  s.**          re
d550: 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  turn true (non-z
d560: 65 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79  ero) if and only
d570: 20 69 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20   if the last.** 
d580: 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68 69           non-whi
d590: 74 65 73 70 61 63 65 20 74 6f 6b 65 6e 20 69 6e  tespace token in
d5a0: 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20   their input is 
d5b0: 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74  a semicolon that
d5c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
d5d0: 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 20 74  not in between t
d5e0: 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44  he BEGIN and END
d5f0: 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49   of a CREATE TRI
d600: 47 47 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20  GGER.**         
d610: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
d620: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
d630: 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54 68  *.** {U10512} Th
d640: 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74  e input to sqlit
d650: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75  e3_complete() mu
d660: 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
d670: 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  minated.**      
d680: 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67      UTF-8 string
d690: 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d  ..**.** {U10513}
d6a0: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71   The input to sq
d6b0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
d6c0: 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  () must be a zer
d6d0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
d6e0: 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20           UTF-16 
d6f0: 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
d700: 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
d710: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
d720: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
d730: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
d740: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
d750: 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
d760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d770: 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
d780: 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
d790: 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
d7a0: 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a  s {F12310}.**.**
d7b0: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64   This routine id
d7c0: 65 6e 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62  entifies a callb
d7d0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
d7e0: 74 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69 6e  t might be.** in
d7f0: 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
d800: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
d810: 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
d820: 62 61 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74  base table .** t
d830: 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
d840: 61 64 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ad or process ha
d850: 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20  s locked..** If 
d860: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
d870: 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
d880: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
d890: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
d8a0: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
d8b0: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
d8c0: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
d8d0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
d8e0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
d8f0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
d900: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a   NULL, then the.
d910: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c  ** callback will
d920: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
d930: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20   two arguments. 
d940: 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72   The.** first ar
d950: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
d960: 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
d970: 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
d980: 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
d990: 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
d9a0: 65 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74  ent to this rout
d9b0: 69 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ine.  The second
d9c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
d9d0: 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74  the handler is t
d9e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
d9f0: 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
da00: 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
da10: 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
da20: 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
da30: 65 6e 74 2e 20 20 20 49 66 20 74 68 65 0a 2a 2a  ent.   If the.**
da40: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
da50: 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
da60: 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
da70: 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
da80: 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
da90: 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
daa0: 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
dab0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
dac0: 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
dad0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
dae0: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
daf0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
db00: 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
db10: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
db20: 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
db30: 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
db40: 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
db50: 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
db60: 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
db70: 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
db80: 72 61 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69  rantee that.** i
db90: 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
dba0: 64 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  d when there is 
dbb0: 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
dbc0: 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65  .** If SQLite de
dbd0: 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
dbe0: 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
dbf0: 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
dc00: 73 75 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61  sult in.** a dea
dc10: 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
dc20: 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
dc30: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
dc40: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
dc50: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
dc60: 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
dc70: 67 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61  g the.** busy ha
dc80: 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
dc90: 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
dca0: 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
dcb0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
dcc0: 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
dcd0: 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
dce0: 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
dcf0: 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
dd00: 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
dd10: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
dd20: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
dd30: 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
dd40: 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
dd50: 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
dd60: 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
dd70: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
dd80: 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
dd90: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
dda0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
ddb0: 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
ddc0: 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
ddd0: 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
dde0: 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
ddf0: 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
de00: 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
de10: 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
de20: 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
de30: 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
de40: 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
de50: 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
de60: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
de70: 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
de80: 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
de90: 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
dea0: 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
deb0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
dec0: 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
ded0: 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
dee0: 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
def0: 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
df00: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  d..**.** The def
df10: 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
df20: 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
df30: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55  * The [SQLITE_BU
df40: 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
df50: 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
df60: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
df70: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
df80: 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
df90: 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
dfa0: 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
dfb0: 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
dfc0: 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
dfd0: 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
dfe0: 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
dff0: 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
e000: 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
e010: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
e020: 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
e030: 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
e040: 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
e050: 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
e060: 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
e070: 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
e080: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
e090: 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
e0a0: 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
e0b0: 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
e0c0: 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
e0d0: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
e0e0: 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
e0f0: 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
e100: 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
e110: 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
e120: 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
e130: 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
e140: 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
e150: 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
e160: 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
e170: 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
e180: 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
e190: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
e1a0: 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63  ].  This error c
e1b0: 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
e1c0: 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
e1d0: 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
e1e0: 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
e1f0: 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
e200: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71  f="http://www.sq
e210: 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63  lite.org/cvstrac
e220: 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
e230: 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
e240: 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
e250: 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
e260: 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
e270: 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
e280: 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
e290: 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
e2a0: 74 2e 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65 20  t..**..** There 
e2b0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
e2c0: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
e2d0: 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
e2e0: 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ch database.** c
e2f0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74  onnection.  Sett
e300: 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
e310: 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
e320: 79 20 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20  y previous one. 
e330: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61  .** Note that ca
e340: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
e350: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77  usy_timeout()] w
e360: 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
e370: 63 6c 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73  clear.** the bus
e380: 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
e390: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
e3a0: 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20  ** {F12311} The 
e3b0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
e3c0: 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f  ndler()] functio
e3d0: 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 62  n replaces the b
e3e0: 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20  usy handler.**  
e3f0: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
e400: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
e410: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
e420: 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31 73  tified by the 1s
e430: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  t.**          pa
e440: 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e  rameter with a n
e450: 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
e460: 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
e470: 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a  e 2nd and 3rd.**
e480: 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
e490: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ters..**.** {F12
e4a0: 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  312} The default
e4b0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
e4c0: 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  r new database c
e4d0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55  onnections is NU
e4e0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  LL..**.** {F1231
e4f0: 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d  4} When two or m
e500: 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ore database con
e510: 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61 20  nection share a 
e520: 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
e530: 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63  shared_cache | c
e540: 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a  ommon cache],.**
e550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75            the bu
e560: 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74  sy handler for t
e570: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
e580: 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79  ection currently
e590: 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
e5a0: 20 20 20 74 68 65 20 63 61 63 68 65 20 69 73 20     the cache is 
e5b0: 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
e5c0: 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72   cache encounter
e5d0: 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20  s a lock..**.** 
e5e0: 7b 46 31 32 33 31 36 7d 20 49 66 20 61 20 62 75  {F12316} If a bu
e5f0: 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
e600: 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ack returns zero
e610: 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74  , then the SQLit
e620: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
e630: 74 65 72 66 61 63 65 20 74 68 61 74 20 70 72 6f  terface that pro
e640: 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e  voked the lockin
e650: 67 20 65 76 65 6e 74 20 77 69 6c 6c 20 72 65 74  g event will ret
e660: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
e670: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
e680: 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51  *.** {F12318} SQ
e690: 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
e6a0: 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  s the busy handl
e6b0: 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  er with two argu
e6c0: 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20  ments which.**  
e6d0: 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
e6e0: 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
e6f0: 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
e700: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
e710: 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
e720: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
e730: 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
e740: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
e750: 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
e760: 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
e770: 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
e780: 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
e790: 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
e7a0: 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
e7b0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
e7c0: 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
e7d0: 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ler should not c
e7e0: 61 6c 6c 20 63 6c 6f 73 65 20 74 68 65 20 64 61  all close the da
e7f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e800: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
e810: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
e820: 65 6e 74 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ent that invoked
e830: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
e840: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
e850: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
e860: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
e870: 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
e880: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
e890: 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
e8a0: 54 69 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d  Timeout {F12340}
e8b0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
e8c0: 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
e8d0: 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
e8e0: 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
e8f0: 0a 2a 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20  .** that sleeps 
e900: 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e  for a while when
e910: 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c   a.** table is l
e920: 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
e930: 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  ler will sleep m
e940: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
e950: 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74  til .** at least
e960: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
e970: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68  ds of sleeping h
e980: 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b  ave been done. {
e990: 46 31 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a  F12343} After.**
e9a0: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
e9b0: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20  ds of sleeping, 
e9c0: 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
e9d0: 72 6e 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63  rns 0 which.** c
e9e0: 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
e9f0: 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
ea00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
ea10: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
ea20: 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
ea30: 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
ea40: 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
ea50: 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
ea60: 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
ea70: 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
ea80: 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
ea90: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
eaa0: 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
eab0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
eac0: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
ead0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
eae0: 65 63 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74  ection.  If anot
eaf0: 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
eb00: 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a   was defined  .*
eb10: 2a 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  * (using [sqlite
eb20: 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
eb30: 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
eb40: 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
eb50: 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
eb60: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
eb70: 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  cleared..**.** I
eb80: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
eb90: 20 7b 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73   {F12341} The [s
eba0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
ebb0: 6f 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  out()] function 
ebc0: 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 70 72  overrides any pr
ebd0: 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
ebe0: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
ebf0: 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
ec00: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
ec10: 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
ec20: 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
ec30: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ec40: 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
ec50: 7b 46 31 32 33 34 33 7d 20 49 66 20 74 68 65 20  {F12343} If the 
ec60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
ec70: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
ec80: 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73  imeout()] is les
ec90: 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  s than.**       
eca0: 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a     or equal to z
ecb0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75  ero, then the bu
ecc0: 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
ecd0: 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a  eared so that.**
ece0: 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75            all su
ecf0: 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67  bsequent locking
ed00: 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74   events immediat
ed10: 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ely return [SQLI
ed20: 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
ed30: 7b 46 31 32 33 34 34 7d 20 49 66 20 74 68 65 20  {F12344} If the 
ed40: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
ed50: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
ed60: 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70  imeout()] is a p
ed70: 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  ositive.**      
ed80: 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68      number N, th
ed90: 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  en a busy handle
eda0: 72 20 69 73 20 73 65 74 20 74 68 61 74 20 72 65  r is set that re
edb0: 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
edc0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
edd0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
ede0: 6e 20 74 68 65 20 56 46 53 20 69 6e 74 65 72 66  n the VFS interf
edf0: 61 63 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  ace until either
ee00: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
ee10: 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
ee20: 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
ee30: 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20  tive sleep time 
ee40: 72 65 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a  reported back.**
ee50: 20 20 20 20 20 20 20 20 20 20 62 79 20 78 53 6c            by xSl
ee60: 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
ee70: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
ee80: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
ee90: 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
eea0: 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
eeb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
eec0: 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
eed0: 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
eee0: 75 65 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a  ueries {F12370}.
eef0: 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
ef00: 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
ef10: 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
ef20: 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
ef30: 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
ef40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
ef50: 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
ef60: 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
ef70: 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
ef80: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
ef90: 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
efa0: 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
efb0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
efc0: 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
efd0: 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
efe0: 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
eff0: 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
f000: 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
f010: 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
f020: 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
f030: 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
f040: 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
f050: 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
f060: 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
f070: 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
f080: 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
f090: 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
f0a0: 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
f0b0: 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
f0c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
f0d0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
f0e0: 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 20 20  UTF-8 strings.  
f0f0: 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
f100: 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
f110: 65 20 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68  e array.  .** Th
f120: 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
f130: 72 73 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f  rs point to zero
f140: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
f150: 6e 67 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e  ngs that .** con
f160: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
f170: 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
f180: 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
f190: 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
f1a0: 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
f1b0: 74 73 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c  ts.  NULL.** val
f1c0: 75 65 73 20 61 72 65 20 67 69 76 65 20 61 20 4e  ues are give a N
f1d0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c  ULL pointer.  Al
f1e0: 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
f1f0: 72 65 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55  re in.** their U
f200: 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
f210: 61 74 65 64 20 73 74 72 69 6e 67 20 72 65 70 72  ated string repr
f220: 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
f230: 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
f240: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
f250: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
f260: 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
f270: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65   consists of one
f280: 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
f290: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
f2a0: 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
f2b0: 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
f2c0: 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
f2d0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
f2e0: 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
f2f0: 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
f300: 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
f310: 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
f320: 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
f330: 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
f340: 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
f350: 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
f360: 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
f370: 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
f380: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
f390: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
f3a0: 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
f3b0: 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
f3c0: 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
f3d0: 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
f3e0: 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
f3f0: 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
f400: 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
f410: 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
f420: 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
f430: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
f440: 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
f450: 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
f460: 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
f470: 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
f480: 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
f490: 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
f4a0: 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
f4b0: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
f4c0: 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
f4d0: 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
f4e0: 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
f4f0: 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
f500: 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
f510: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
f520: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
f530: 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
f540: 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
f550: 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
f560: 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
f570: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
f580: 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
f590: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
f5a0: 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
f5b0: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
f5c0: 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
f5d0: 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
f5e0: 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
f5f0: 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
f600: 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
f610: 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
f620: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
f630: 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
f640: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
f650: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
f660: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
f670: 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
f680: 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
f690: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
f6a0: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
f6b0: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
f6c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
f6d0: 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
f6e0: 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
f6f0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
f700: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
f710: 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
f720: 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
f730: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
f740: 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
f750: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
f760: 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
f770: 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
f780: 6f 75 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68  ould .** pass th
f790: 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
f7a0: 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
f7b0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
f7c0: 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
f7d0: 6f 20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  o .** release th
f7e0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
f7f0: 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
f800: 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
f810: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
f820: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
f830: 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
f840: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
f850: 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
f860: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
f870: 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
f880: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
f890: 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a  ectly.  Only .**
f8a0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
f8b0: 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
f8c0: 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
f8d0: 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
f8e0: 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
f8f0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
f900: 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
f910: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
f920: 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
f930: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
f940: 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
f950: 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
f960: 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
f970: 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
f980: 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
f990: 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
f9a0: 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
f9b0: 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
f9c0: 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
f9d0: 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
f9e0: 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
f9f0: 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
fa00: 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
fa10: 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
fa20: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
fa30: 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
fa40: 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
fa50: 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
fa60: 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
fa70: 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
fa80: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
fa90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
faa0: 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  msg()]..**.** IN
fab0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
fac0: 7b 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73  {F12371} If a [s
fad0: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
fae0: 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f  ()] fails a memo
faf0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ry allocation, t
fb00: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
fb10: 69 74 20 66 72 65 65 73 20 74 68 65 20 72 65 73  it frees the res
fb20: 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20  ult table under 
fb30: 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62  construction, ab
fb40: 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  orts the.**     
fb50: 20 20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72       query in pr
fb60: 6f 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e 79  ocess, skips any
fb70: 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65 72   subsequent quer
fb80: 69 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a  ies, sets the.**
fb90: 20 20 20 20 20 20 20 20 20 20 2a 72 65 73 75 6c            *resul
fba0: 74 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65  tp output pointe
fbb0: 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65  r to NULL and re
fbc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
fbd0: 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  MEM]..**.** {F12
fbe0: 33 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c  373} If the ncol
fbf0: 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  umn parameter to
fc00: 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
fc10: 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55  ble()] is not NU
fc20: 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
fc30: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  hen [sqlite3_get
fc40: 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20  _table()] write 
fc50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
fc60: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
fc70: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
fc80: 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
fc90: 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69   into *ncolumn i
fca0: 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a  f the query is.*
fcb0: 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65  *          succe
fcc0: 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75  ssful (if the fu
fcd0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53  nction returns S
fce0: 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a  QLITE_OK)..**.**
fcf0: 20 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68 65   {F12374} If the
fd00: 20 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72 20   nrow parameter 
fd10: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  to [sqlite3_get_
fd20: 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20  table()] is not 
fd30: 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
fd40: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67   then [sqlite3_g
fd50: 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74  et_table()] writ
fd60: 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
fd70: 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  rows in the.**  
fd80: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
fd90: 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
fda0: 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68  into *nrow if th
fdb0: 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20  e query is.**   
fdc0: 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66 75         successfu
fdd0: 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74 69  l (if the functi
fde0: 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  on returns SQLIT
fdf0: 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  E_OK)..**.** {F1
fe00: 32 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  2376} The [sqlit
fe10: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
fe20: 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74  function sets it
fe30: 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  s *ncolumn value
fe40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
fe50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
fe60: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
fe70: 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
fe80: 75 65 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20 20  uery in the.**  
fe90: 20 20 20 20 20 20 20 20 73 71 6c 20 70 61 72 61          sql para
fea0: 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72  meter, or to zer
feb0: 6f 20 69 66 20 74 68 65 20 71 75 65 72 79 20 69  o if the query i
fec0: 6e 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70  n sql has an emp
fed0: 74 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ty.**          r
fee0: 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e  esult set..*/.in
fef0: 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
ff00: 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ble(.  sqlite3*,
ff10: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
ff20: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
ff30: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
ff40: 20 2a 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53   *sql,      /* S
ff50: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
ff60: 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
ff70: 70 52 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a  pResult,      /*
ff80: 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
ff90: 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
ffa0: 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nrow,           
ffb0: 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
ffc0: 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
ffd0: 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
ffe0: 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  *ncolumn,       
fff0: 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
10000 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
10010 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
10020 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
10030 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
10040 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
10050 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
10060 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
10070 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
10080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10090 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
100a0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
100b0 6e 73 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a  ns {F17400}.**.*
100c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
100d0 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20   are workalikes 
100e0 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
100f0 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
10100 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
10110 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10120 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rary..**.** The 
10130 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
10140 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
10150 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
10160 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
10170 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
10180 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
10190 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
101a0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
101b0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
101c0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
101d0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
101e0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
101f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
10200 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
10210 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
10220 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
10230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
10240 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
10250 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
10260 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
10270 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
10280 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
10290 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
102a0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
102b0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
102c0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
102d0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
102e0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
102f0 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
10300 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
10310 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
10320 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
10330 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
10340 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
10350 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
10360 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
10370 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
10380 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
10390 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
103a0 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
103b0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
103c0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
103d0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
103e0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
103f0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
10400 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
10410 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
10420 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
10430 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
10440 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
10450 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
10460 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
10470 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
10480 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
10490 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
104a0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
104b0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
104c0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
104d0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
104e0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
104f0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
10500 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
10510 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
10520 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
10530 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
10540 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
10550 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
10560 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
10570 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
10580 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
10590 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
105a0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
105b0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
105c0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
105d0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
105e0 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
105f0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
10600 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
10610 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
10620 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
10630 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
10640 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
10650 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
10660 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
10670 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
10680 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
10690 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
106a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
106b0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
106c0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
106d0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
106e0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
106f0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
10700 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
10710 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
10720 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
10730 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
10740 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
10750 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
10760 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
10770 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
10780 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
10790 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
107a0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
107b0 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
107c0 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
107d0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
107e0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
107f0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
10800 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
10810 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
10820 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
10830 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
10840 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
10850 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
10860 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
10870 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
10880 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
10890 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
108a0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
108b0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
108c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
108d0 61 6d 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73  ample, so some s
108e0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63  tring variable c
108f0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
10900 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
10910 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
10920 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
10930 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
10940 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
10950 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
10960 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
10970 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
10980 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
10990 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
109a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
109b0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
109c0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
109d0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
109e0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
109f0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
10a00 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
10a10 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
10a20 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
10a30 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
10a40 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
10a50 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
10a60 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
10a70 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
10a80 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
10a90 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
10aa0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
10ab0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
10ac0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
10ad0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
10ae0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
10af0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
10b00 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
10b10 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
10b20 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
10b30 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
10b40 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
10b50 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
10b60 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
10b70 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
10b80 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
10b90 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
10ba0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
10bb0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
10bc0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
10bd0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
10be0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
10bf0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
10c00 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
10c10 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
10c20 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
10c30 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
10c40 79 6f 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c  you.** should al
10c50 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
10c60 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
10c70 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
10c80 74 6f 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20  to a string .** 
10c90 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54  literal..**.** T
10ca0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
10cb0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
10cc0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
10cd0 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
10ce0 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
10cf0 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
10d00 73 74 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74  string.  Or if t
10d10 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
10d20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  the argument.** 
10d30 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
10d40 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
10d50 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
10d60 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20  "NULL" (without 
10d70 73 69 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73  single.** quotes
10d80 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
10d90 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e  e %Q option. {EN
10da0 44 7d 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  D}  So, for exam
10db0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
10dc0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
10dd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
10de0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
10df0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
10e00 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
10e10 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
10e20 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
10e30 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
10e40 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
10e50 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
10e60 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
10e70 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
10e80 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
10e90 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
10ea0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
10eb0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
10ec0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
10ed0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
10ee0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
10ef0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
10f00 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
10f10 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
10f20 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
10f30 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
10f40 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
10f50 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
10f60 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
10f70 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
10f80 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
10f90 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
10fa0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
10fb0 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
10fc0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
10fd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20  .**.** {F17403} 
10fe0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70   The [sqlite3_mp
10ff0 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71  rintf()] and [sq
11000 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
11010 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
11020 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
11030 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73   either pointers
11040 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
11050 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
11060 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20  s held in.**    
11070 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62         memory ob
11080 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
11090 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
110a0 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
110b0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
110c0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
110d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69  e3_malloc()] fai
110e0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30  ls..**.** {F1740
110f0 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  6}  The [sqlite3
11100 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
11110 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20  erface writes a 
11120 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
11130 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46  **           UTF
11140 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74  -8 string into t
11150 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65  he buffer pointe
11160 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  d to by the seco
11170 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
11180 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64            provid
11190 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73  ed that the firs
111a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67  t parameter is g
111b0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
111c0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d  ..**.** {F17407}
111d0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
111e0 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
111f0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72  face does not wr
11200 69 74 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  ites slots of.**
11210 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
11220 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
11230 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11240 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
11250 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
11260 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
11270 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
11280 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11290 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
112a0 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
112b0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
112c0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
112d0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
112e0 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
112f0 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20  ecification..** 
11300 20 20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69    .*/.char *sqli
11310 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
11320 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
11330 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
11340 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
11350 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
11360 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
11370 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
11380 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
11390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
113a0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
113b0 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31  on Subsystem {F1
113c0 37 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  7300}.**.** The 
113d0 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65  SQLite core  use
113e0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
113f0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
11400 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
11410 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
11420 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
11430 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
11440 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
11450 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
11460 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
11470 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
11480 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
11490 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
114a0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
114b0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
114c0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
114d0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
114e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
114f0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
11500 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
11510 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
11520 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
11530 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
11540 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
11550 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
11560 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
11570 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
11580 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
11590 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
115a0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
115b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
115c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
115d0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
115e0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
115f0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
11600 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
11610 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
11620 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
11630 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69  .** Calling sqli
11640 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
11650 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
11660 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
11670 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
11680 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
11690 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
116a0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
116b0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
116c0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54  ht be reused.  T
116d0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
116e0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
116f0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
11700 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
11710 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
11720 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
11730 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
11740 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
11750 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
11760 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
11770 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
11780 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
11790 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
117a0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
117b0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
117c0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
117d0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
117e0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
117f0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
11800 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
11810 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
11820 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
11830 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
11840 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
11850 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
11860 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
11870 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
11880 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
11890 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
118a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
118b0 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  or sqlite3_free(
118c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
118d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
118e0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
118f0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
11900 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
11910 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
11920 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
11930 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
11940 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
11950 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
11960 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
11970 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
11980 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
11990 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72  ter.  If the fir
119a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
119b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
119c0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
119d0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
119e0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
119f0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
11a00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
11a10 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
11a20 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
11a30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
11a40 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49  _realloc()..** I
11a50 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
11a60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
11a70 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
11a80 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
11a90 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
11aa0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
11ab0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
11ac0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
11ad0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
11ae0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
11af0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
11b00 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53  _realloc()..** S
11b10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
11b20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
11b30 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
11b40 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
11b50 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
11b60 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
11b70 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
11b80 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
11b90 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73  able..** If M is
11ba0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
11bb0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
11bc0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
11bd0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
11be0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
11bf0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
11c00 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
11c10 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
11c20 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
11c30 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
11c40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
11c50 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
11c60 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   If sqlite3_real
11c70 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
11c80 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
11c90 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
11ca0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
11cb0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
11cc0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
11cd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
11ce0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
11cf0 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
11d00 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
11d10 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
11d20 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a  undary. {END}.**
11d30 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
11d40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
11d50 2a 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20  * of the memory 
11d60 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
11d70 73 74 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61  stem uses the ma
11d80 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
11d90 29 0a 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20  ).** and free() 
11da0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
11db0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11dc0 72 79 2e 20 7b 46 31 37 33 38 32 7d 20 48 6f 77  ry. {F17382} How
11dd0 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c  ever, if .** SQL
11de0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11df0 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69  with the followi
11e00 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ng C preprocesso
11e10 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62  r macro.**.** <b
11e20 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54  lockquote> SQLIT
11e30 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69  E_MEMORY_SIZE=<i
11e40 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b  >NNN</i> </block
11e50 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65  quote>.**.** whe
11e60 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73  re <i>NNN</i> is
11e70 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
11e80 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20  n SQLite create 
11e90 61 20 73 74 61 74 69 63 0a 2a 2a 20 61 72 72 61  a static.** arra
11ea0 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 3c 69  y of at least <i
11eb0 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69  >NNN</i> bytes i
11ec0 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 20 74  n size and use t
11ed0 68 61 74 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72  hat array.** for
11ee0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
11ef0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
11f00 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e  ation needs. {EN
11f10 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a  D}  Additional.*
11f20 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
11f30 6f 72 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  or options may b
11f40 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
11f50 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
11f60 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
11f70 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
11f80 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
11f90 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
11fa0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
11fb0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
11fc0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
11fd0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
11fe0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
11ff0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
12000 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
12010 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
12020 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
12030 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
12040 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
12050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12060 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64  s can be.** used
12070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
12080 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
12090 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
120a0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
120b0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
120c0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
120d0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
120e0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
120f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
12100 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
12110 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
12120 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
12130 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
12140 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
12150 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
12160 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
12170 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
12180 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
12190 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
121a0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
121b0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
121c0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
121d0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
121e0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
121f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
12200 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d  :.**.** {F17303}
12210 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
12220 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
12230 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
12240 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  er a pointer to 
12250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 65  .**           ne
12260 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20  wly checked-out 
12270 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73  block of at leas
12280 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  t N bytes of mem
12290 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
122a0 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20   that is 8-byte 
122b0 61 6c 69 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20  aligned, .**    
122c0 20 20 20 20 20 20 20 6f 72 20 69 74 20 72 65 74         or it ret
122d0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20  urns NULL if it 
122e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c  is unable to ful
122f0 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
12300 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d  ..**.** {F17304}
12310 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
12320 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
12330 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ace returns a NU
12340 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a  LL pointer if.**
12350 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20             N is 
12360 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
12370 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  al to zero..**.*
12380 2a 20 7b 46 31 37 33 30 35 7d 20 20 54 68 65 20  * {F17305}  The 
12390 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
123a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65  ] interface rele
123b0 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76  ases memory prev
123c0 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
123d0 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f      returned fro
123e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
123f0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
12400 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
12410 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67            making
12420 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f   it available fo
12430 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  r reuse..**.** {
12440 46 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20  F17306}  A call 
12450 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
12460 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72  (NULL)] is a har
12470 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
12480 2a 2a 20 7b 46 31 37 33 31 30 7d 20 20 41 20 63  ** {F17310}  A c
12490 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
124a0 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73  realloc(0,N)] is
124b0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
124c0 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
124d0 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d     to [sqlite3_m
124e0 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  alloc(N)]..**.**
124f0 20 7b 46 31 37 33 31 32 7d 20 20 41 20 63 61 6c   {F17312}  A cal
12500 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
12510 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65  alloc(P,0)] is e
12520 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
12530 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
12540 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
12550 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  e(P)]..**.** {F1
12560 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74  7315}  The SQLit
12570 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c  e core uses [sql
12580 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
12590 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
125a0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
125b0 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66    and [sqlite3_f
125c0 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f  ree()] for all o
125d0 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  f its memory all
125e0 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  ocation and.**  
125f0 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63           dealloc
12600 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  ation needs..**.
12610 2a 2a 20 7b 46 31 37 33 31 38 7d 20 20 54 68 65  ** {F17318}  The
12620 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
12630 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  c(P,N)] interfac
12640 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
12650 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
12660 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f          to a blo
12670 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75  ck of checked-ou
12680 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  t memory of at l
12690 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
126a0 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
126b0 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
126c0 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
126d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
126e0 2a 2a 20 7b 46 31 37 33 32 31 7d 20 20 57 68 65  ** {F17321}  Whe
126f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
12700 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
12710 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
12720 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
12730 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
12740 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79  s the first K by
12750 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66  tes of content f
12760 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e  rom P into the n
12770 65 77 6c 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  ewly allocated.*
12780 2a 20 20 20 20 20 20 20 20 20 20 20 77 68 65 72  *           wher
12790 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65  e K is the lesse
127a0 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73  r of N and the s
127b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
127c0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  r P..**.** {F173
127d0 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  22}  When [sqlit
127e0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
127f0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e   returns a non-N
12800 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20  ULL pointer, it 
12810 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
12820 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20     releases the 
12830 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
12840 7b 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b  {F17323}  When [
12850 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
12860 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55  P,N)] returns NU
12870 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50  LL, the buffer P
12880 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
12890 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72   not modified or
128a0 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
128b0 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
128c0 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68  .** {U17350}  Th
128d0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
128e0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
128f0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
12900 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
12910 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73  **           mus
12920 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
12930 20 6f 72 20 65 6c 73 65 20 61 20 70 6f 69 6e 74   or else a point
12940 65 72 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  er obtained from
12950 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20   a prior.**     
12960 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
12970 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
12980 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
12990 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
129a0 61 74 20 68 61 73 0a 2a 2a 20 20 20 20 20 20 20  at has.**       
129b0 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c      not been rel
129c0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  eased..**.** {U1
129d0 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69  7351}  The appli
129e0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
129f0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
12a00 79 20 70 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20  y part of .**   
12a10 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20          a block 
12a20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
12a30 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
12a40 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ased using.**   
12a50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
12a60 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
12a70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
12a80 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  .**.*/.void *sql
12a90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
12aa0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
12ab0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
12ac0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
12ad0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
12ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12af0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
12b00 20 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37   Statistics {F17
12b10 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  370}.**.** SQLit
12b20 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
12b30 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
12b40 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
12b50 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
12b60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12b70 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
12b80 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
12b90 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
12ba0 28 29 5d 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ()].** the memor
12bb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
12bc0 73 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20  system included 
12bd0 77 69 74 68 69 6e 20 74 68 65 20 53 51 4c 69 74  within the SQLit
12be0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
12bf0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  NTS:.**.** {F173
12c00 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
12c10 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
12c20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12c30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12c40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
12c50 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
12c60 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
12c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 6d 61  .**          (ma
12c80 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
12c90 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  reed)..**.** {F1
12ca0 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  7373} The [sqlit
12cb0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
12cc0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
12cd0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
12ce0 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  um.**          v
12cf0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
12d00 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
12d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 69 6e  .**          sin
12d20 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
12d30 72 20 6d 61 72 6b 20 77 61 73 20 6c 61 73 74 20  r mark was last 
12d40 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  reset..**.** {F1
12d50 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73  7374} The values
12d60 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
12d70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
12d80 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  d()] and.**     
12d90 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
12da0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12db0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
12dc0 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20  erhead.**       
12dd0 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69     added by SQLi
12de0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
12df0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
12e00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
12e10 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20  **          but 
12e20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
12e30 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
12e40 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
12e50 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20  library.**      
12e60 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61      routines tha
12e70 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
12e80 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
12e90 2a 20 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54  * .** {F17375} T
12ea0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
12eb0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
12ec0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
12ed0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  t value of.**   
12ee0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
12ef0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
12f00 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
12f10 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
12f20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
12f30 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
12f40 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
12f50 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
12f60 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
12f70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
12f80 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
12f90 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
12fa0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
12fb0 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68       prior to th
12fc0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
12fd0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
12fe0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
12ff0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
13000 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
13010 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
13020 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
13030 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
13040 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
13050 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37  r Generator {F17
13060 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  390}.**.** SQLit
13070 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
13080 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
13090 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
130a0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
130b0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
130c0 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
130d0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
130e0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
130f0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
13100 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
13110 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
13120 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
13130 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
13140 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
13150 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
13160 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
13170 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
13180 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
13190 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
131a0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
131b0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
131c0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
131d0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
131e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
131f0 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
13200 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
13210 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54  uffer P..**.** T
13220 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
13230 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
13240 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
13250 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
13260 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
13270 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
13280 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
13290 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
132a0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
132b0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
132c0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
132d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
132e0 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75  ct..** On all su
132f0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
13300 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
13310 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
13320 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
13330 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
13340 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
13350 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
13360 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
13370 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  method..**.** IN
13380 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
13390 7b 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71  {F17392} The [sq
133a0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
133b0 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  (N,P)] interface
133c0 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20   writes N bytes 
133d0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  of.**          h
133e0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
133f0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
13400 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a  to buffer P..*/.
13410 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
13420 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
13430 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
13440 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
13450 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
13460 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
13470 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12500}.**.** Th
13480 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
13490 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
134a0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
134b0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
134c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
134d0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
134e0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
134f0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75  ument..** The au
13500 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
13510 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
13520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
13530 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
13540 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
13550 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
13560 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
13570 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
13580 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
13590 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
135a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
135b0 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
135c0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
135d0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
135e0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
135f0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
13600 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
13610 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
13620 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
13630 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
13640 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
13650 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
13660 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
13670 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
13680 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
13690 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
136a0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
136b0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
136c0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
136d0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
136e0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
136f0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
13700 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
13710 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
13720 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
13730 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
13740 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
13750 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
13760 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
13770 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
13780 2e 20 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  .   If the autho
13790 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
137a0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
137b0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
137c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
137d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
137e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
137f0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   then [sqlite3_p
13800 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
13810 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
13820 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
13830 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
13840 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
13850 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
13860 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
13870 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
13880 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
13890 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
138a0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
138b0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
138c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
138d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
138e0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
138f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
13900 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
13910 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
13920 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
13930 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
13940 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
13950 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
13960 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
13970 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
13980 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
13990 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
139a0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
139b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
139c0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
139d0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
139e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
139f0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
13a00 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
13a10 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
13a20 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
13a30 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
13a40 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
13a50 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
13a60 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
13a70 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
13a80 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
13a90 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
13aa0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
13ab0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
13ac0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
13ad0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
13ae0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
13af0 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
13b00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13b10 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
13b20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
13b30 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
13b40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
13b50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
13b60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
13b70 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68  interface..** Th
13b80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13b90 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
13ba0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
13bb0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50   .** [SQLITE_COP
13bc0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
13bd0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
13be0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
13bf0 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61  ction.** to be a
13c00 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74  uthorized. The t
13c10 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
13c20 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  th.** parameters
13c30 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
13c40 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
13c50 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
13c60 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64  t contain .** ad
13c70 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
13c80 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
13c90 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
13ca0 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ed..**.** An aut
13cb0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
13cc0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
13cd0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
13ce0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
13cf0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
13d00 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65  rusted.** source
13d10 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
13d20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
13d30 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  nts do not try t
13d40 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a  o access data.**
13d50 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20 6e   that they are n
13d60 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
13d70 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
13d80 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a  do not try to.**
13d90 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
13da0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
13db0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
13dc0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
13dd0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
13de0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
13df0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
13e00 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
13e10 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
13e20 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
13e30 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
13e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
13e50 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
13e60 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
13e70 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
13e80 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
13e90 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
13ea0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
13eb0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
13ec0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
13ed0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
13ee0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
13ef0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
13f00 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
13f10 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
13f20 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
13f30 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
13f40 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
13f50 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
13f60 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
13f70 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
13f80 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
13f90 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
13fa0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
13fb0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
13fc0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
13fd0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
13fe0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
13ff0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
14000 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
14010 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
14020 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
14030 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
14040 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
14050 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
14060 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
14070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14080 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
14090 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
140a0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
140b0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
140c0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
140d0 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20   call.  Disable 
140e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
140f0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
14100 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
14110 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
14120 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
14130 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  efault..**.** No
14140 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
14150 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
14160 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
14170 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69  during .** [sqli
14180 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
14190 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
141a0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
141b0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
141c0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
141d0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
141e0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
141f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
14200 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
14210 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  501} The [sqlite
14220 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
14230 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
14240 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a  ce registers a.*
14250 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
14260 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
14270 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ith database con
14280 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
14290 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75   {F12502} The au
142a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
142b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
142c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
142d0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  re.**          b
142e0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
142f0 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20  .** {F12503} If 
14300 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
14310 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
14320 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
14330 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
14340 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
14350 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
14360 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
14370 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
14380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
14390 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
143a0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
143b0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20  hat caused.**   
143c0 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f         the autho
143d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74  rizer callback t
143e0 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c  o run shall fail
143f0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
14400 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
14410 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  OR] error code a
14420 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
14430 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
14440 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20  .**.** {F12504} 
14450 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
14460 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
14470 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
14480 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  , the operation.
14490 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63  **          desc
144a0 72 69 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e  ribed is coded n
144b0 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ormally..**.** {
144c0 46 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65  F12505} When the
144d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
144e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
144f0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
14500 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
14510 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
14520 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
14530 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
14540 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  d the.**        
14550 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
14560 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
14570 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20  ll fail.**      
14580 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c      with an [SQL
14590 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
145a0 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72   code and an err
145b0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
145c0 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e         explainin
145d0 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73  g that access is
145e0 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   denied..**.** {
145f0 46 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61  F12506} If the a
14600 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
14610 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
14620 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
14630 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
14640 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51  callback) is [SQ
14650 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74  LITE_READ] and t
14660 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
14670 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
14680 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
14690 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
146a0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
146b0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
146c0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
146d0 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
146e0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
146f0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
14700 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
14710 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
14720 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
14730 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
14740 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
14750 0a 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20  .** {F12507} If 
14760 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
14770 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
14780 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
14790 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
147a0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
147b0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
147c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
147d0 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
147e0 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
147f0 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
14800 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
14810 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
14820 5f 44 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b  _DENY]. .**.** {
14830 46 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73  F12510} The firs
14840 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
14850 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
14860 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
14870 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
14880 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
14890 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
148a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
148b0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  er()] interface.
148c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20  .**.** {F12511} 
148d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
148e0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
148f0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
14900 65 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er .**          
14910 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
14920 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
14930 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
14940 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
14950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
14960 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
14970 2a 0a 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68  *.** {F12512} Th
14980 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
14990 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
149a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
149b0 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
149c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
149d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
149e0 6e 74 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20  ntain .**       
149f0 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65     additional de
14a00 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
14a10 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
14a20 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
14a30 46 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c  F12520} Each cal
14a40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65  l to [sqlite3_se
14a50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
14a60 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
14a70 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72            any pr
14a80 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c  eviously install
14a90 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  ed authorizer..*
14aa0 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20  *.** {F12521} A 
14ab0 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20  NULL authorizer 
14ac0 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75  means that no au
14ad0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20  thorization.**  
14ae0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
14af0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
14b00 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20  ** {F12522} The 
14b10 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a  default authoriz
14b20 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  er is NULL..*/.i
14b30 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
14b40 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
14b50 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
14b60 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
14b70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
14b80 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
14b90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
14ba0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
14bb0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
14bc0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
14bd0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20  er Return Codes 
14be0 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12590}.**.** T
14bf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
14c00 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
14c10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14c20 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
14c30 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
14c40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
14c50 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
14c60 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
14c70 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
14c80 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
14c90 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
14ca0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
14cb0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
14cc0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
14cd0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
14ce0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
14cf0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
14d00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
14d10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14d20 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
14d30 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
14d40 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
14d50 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
14d60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
14d70 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
14d80 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
14d90 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
14da0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
14db0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
14dc0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
14dd0 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12550}.**.** 
14de0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
14df0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
14e00 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
14e10 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
14e20 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
14e30 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
14e40 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20  horizer certain 
14e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
14e60 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
14e70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14e80 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
14e90 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
14ea0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
14eb0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
14ec0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
14ed0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
14ee0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
14ef0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
14f00 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
14f10 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
14f20 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
14f30 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
14f40 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
14f50 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
14f60 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  ration is to be 
14f70 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
14f80 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
14f90 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
14fa0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
14fb0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
14fc0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
14fd0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
14fe0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
14ff0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
15000 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
15010 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15020 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20  meter.  The 5th 
15030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15040 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
15050 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
15060 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
15070 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
15080 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69  mp", .** etc.) i
15090 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54  f applicable.  T
150a0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
150b0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
150c0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
150d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
150e0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
150f0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
15100 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
15110 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
15120 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
15130 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
15140 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
15150 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74  ectly from .** t
15160 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
15170 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
15180 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  NTS:.**.** {F125
15190 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  51} The second p
151a0 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a  arameter to an .
151b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
151c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
151d0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
151e0 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c   callback] is al
151f0 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ways an integer.
15200 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
15210 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
15220 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74  rizer code] that
15230 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
15240 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
15250 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68     is being auth
15260 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
15270 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61  12552} The 3rd a
15280 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
15290 73 20 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20  s to the .**    
152a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
152b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
152c0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
152d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
152e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
152f0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
15300 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
15310 67 20 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20  g on which .**  
15320 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
15330 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
15340 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
15350 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15360 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
15370 46 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  F12553} The 5th 
15380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
153a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
153b0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
153c0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
153d0 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
153e0 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62      of the datab
153f0 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d  ase (example: "m
15400 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74  ain", "temp", et
15410 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
15420 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34  e..**.** {F12554
15430 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65  } The 6th parame
15440 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
15450 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
15460 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
15470 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15480 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
15490 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
154a0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
154b0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
154c0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
154d0 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ble for.**      
154e0 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61      the access a
154f0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
15500 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
15510 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
15520 79 20 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20  y from .**      
15530 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51      top-level SQ
15540 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
15550 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15560 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
15570 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
15580 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
15590 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
155a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
155b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
155c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
155d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
155e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
155f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
15600 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
15610 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
15620 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15630 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15640 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
15650 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
15660 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
15670 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
15680 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
15690 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
156a0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
156b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
156c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
156d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
156e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
156f0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
15700 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
15710 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
15720 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15730 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
15740 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
15750 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
15760 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15780 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
15790 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
157a0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
157b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
157c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157d0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
157e0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
157f0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
15800 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15820 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
15830 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
15840 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
15850 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15870 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
15880 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
15890 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
158a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
158b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
158c0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
158d0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
158e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
158f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
15910 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
15920 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
15930 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
15940 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
15950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
15960 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
15970 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
15980 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
15990 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
159a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
159b0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
159c0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
159d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
159e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
159f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
15a00 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
15a10 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
15a20 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
15a30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15a40 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
15a50 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
15a60 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
15a70 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
15a80 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
15a90 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
15aa0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
15ab0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
15ac0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
15ad0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
15ae0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
15af0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
15b00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
15b10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
15b20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
15b30 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
15b40 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
15b50 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
15b60 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
15b70 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
15b80 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
15b90 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
15ba0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
15bb0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
15bc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
15bd0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
15be0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
15bf0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
15c00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
15c10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
15c20 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
15c30 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
15c40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15c50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
15c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15c70 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
15c80 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
15c90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
15ca0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
15cb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15cc0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
15cd0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
15ce0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
15cf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
15d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15d10 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
15d20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
15d30 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
15d40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
15d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15d60 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
15d70 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
15d80 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
15d90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
15da0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
15db0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
15dc0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
15dd0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
15de0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
15df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
15e00 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
15e10 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
15e20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
15e30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
15e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
15e50 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
15e60 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
15e70 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
15e80 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
15e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
15ea0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
15eb0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
15ec0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
15ed0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
15ee0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
15ef0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
15f00 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e  31   /* Function
15f10 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
15f20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
15f30 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
15f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
15f50 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
15f60 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
15f70 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
15f80 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
15f90 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38  Functions {F1228
15fa0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
15fb0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
15fc0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15fd0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
15fe0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
15ff0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
16000 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
16010 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
16020 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
16030 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
16040 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
16050 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
16060 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
16070 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
16080 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
16090 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
160a0 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
160b0 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
160c0 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
160d0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
160e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
160f0 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
16100 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
16110 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
16120 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
16130 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
16140 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
16150 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
16160 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
16170 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
16180 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
16190 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
161a0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
161b0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
161c0 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 63  er..** .** The c
161d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
161e0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
161f0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
16200 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
16210 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
16220 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
16230 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
16240 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
16250 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
16260 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
16270 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
16280 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
16290 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
162a0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
162b0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
162c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f   The sqlite3_pro
162d0 66 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75  file() API is cu
162e0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
162f0 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
16300 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63  and.** is subjec
16310 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
16320 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75  emoval in a futu
16330 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a  re release..**.*
16340 2a 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65  * The trigger re
16350 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20  porting feature 
16360 6f 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  of the trace cal
16370 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65  lback is conside
16380 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  red.** experimen
16390 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
163a0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20  ct to change or 
163b0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
163c0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46  e releases..** F
163d0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
163e0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  f SQLite might a
163f0 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63  lso add new trac
16400 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69  e callback .** i
16410 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  nvocations..**.*
16420 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
16430 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65  .** {F12281} The
16440 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16450 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
16460 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
16470 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
16480 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51    whenever an SQ
16490 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  L statement firs
164a0 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63  t begins to exec
164b0 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ute and.**      
164c0 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20 74      whenever a t
164d0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
164e0 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  m first begins t
164f0 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  o run..**.** {F1
16500 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20  2282} Each call 
16510 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
16520 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  e()] overrides t
16530 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  he previously.**
16540 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
16550 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62  ered trace callb
16560 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ack..**.** {F122
16570 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65  83} A NULL trace
16580 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c   callback disabl
16590 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a  es tracing..**.*
165a0 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65 20 66  * {F12284} The f
165b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
165c0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
165d0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
165e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
165f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
16600 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  as the 3rd argum
16610 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
16620 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  trace()]..**.** 
16630 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73 65 63  {F12285} The sec
16640 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
16650 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
16660 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  ck is a.**      
16670 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
16680 74 65 64 20 55 54 46 38 20 73 74 72 69 6e 67 20  ted UTF8 string 
16690 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f  containing the o
166a0 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20  riginal text.** 
166b0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
166c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
166d0 20 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69   it was passed i
166e0 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nto [sqlite3_pre
166f0 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20  pare_v2()].**   
16700 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71         or the eq
16710 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20  uivalent, or an 
16720 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69  SQL comment indi
16730 63 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e  cating the begin
16740 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
16750 20 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75   of a trigger su
16760 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20  bprogram..**.** 
16770 7b 46 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c  {F12287} The cal
16780 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
16790 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71  egistered by [sq
167a0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
167b0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
167c0 20 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20          as each 
167d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
167e0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nishes..**.** {F
167f0 31 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74  12288} The first
16800 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16810 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
16820 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
16830 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
16840 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
16850 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
16860 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
16870 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  289} The second 
16880 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16890 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
168a0 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  k is a.**       
168b0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
168c0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  ed UTF-8 string 
168d0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  that contains th
168e0 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20  e complete text 
168f0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
16900 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
16910 20 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65   as it was proce
16920 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ssed by [sqlite3
16930 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
16940 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
16950 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a  e equivalent..**
16960 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65  .** {F12290} The
16970 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16980 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
16990 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
169a0 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20  estimate.**     
169b0 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62       of the numb
169c0 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
169d0 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  s of wall-clock 
169e0 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f  time required to
169f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e  .**          run
16a00 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16a10 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f  nt from start to
16a20 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64   finish..*/.void
16a30 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
16a40 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
16a50 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
16a60 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
16a70 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
16a80 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
16a90 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
16aa0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
16ab0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
16ac0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
16ad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16ae0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
16af0 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  s Callbacks {F12
16b00 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  910}.**.** This 
16b10 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
16b20 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
16b30 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
16b40 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
16b50 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
16b60 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
16b70 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
16b80 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
16b90 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
16ba0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
16bb0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
16bc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
16bd0 2e 20 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  .   An example u
16be0 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
16bf0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
16c00 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
16c10 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
16c20 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
16c30 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
16c40 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16c50 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
16c60 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
16c70 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
16c80 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
16c90 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
16ca0 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
16cb0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
16cc0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
16cd0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
16ce0 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65  .** {F12911} The
16cf0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16d00 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
16d10 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
16d20 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a  ss_handler()].**
16d30 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
16d40 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
16d50 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
16d60 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
16d70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16d80 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
16d90 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20  ** {F12912} The 
16da0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
16db0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
16dc0 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
16dd0 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  rtual.**        
16de0 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65    machine opcode
16df0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
16e00 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16e10 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  t to .**        
16e20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70    the [sqlite3_p
16e30 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
16e40 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67  )] call that reg
16e50 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
16e60 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
16e70 2e 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66  .  <todo>What if
16e80 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
16e90 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  1?</todo>.**.** 
16ea0 7b 46 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f  {F12913} The pro
16eb0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
16ec0 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66  tself is identif
16ed0 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64  ied by the third
16ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
16ef0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
16f00 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
16f10 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  er()]..**.** {F1
16f20 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68  2914} The fourth
16f30 20 61 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74   argument [sqlit
16f40 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
16f50 6c 65 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20  ler()] is a.*** 
16f60 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69          void poi
16f70 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
16f80 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
16f90 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
16fa0 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
16fb0 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
16fc0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35  d..**.** {F12915
16fd0 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
16fe0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
16ff0 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72  results in fewer
17000 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
17010 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e    N opcodes bein
17020 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20  g executed,.**  
17030 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
17040 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
17050 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
17060 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a  ked. {END}.** .*
17070 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79  * {F12916} Every
17080 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
17090 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
170a0 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  er()].**        
170b0 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79    overwrites any
170c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
170d0 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73 20  stered progress 
170e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  handler..**.** {
170f0 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70  F12917} If the p
17100 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
17110 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
17120 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73   then no progres
17130 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  s.**          ha
17140 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  ndler is invoked
17150 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d  ..**.** {F12918}
17160 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
17170 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17180 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72  s a result other
17190 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a   than 0, then.**
171a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65            the be
171b0 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b  havior is a if [
171c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
171d0 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61  t()] had been ca
171e0 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  lled..*/.void sq
171f0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
17200 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
17210 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
17220 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
17230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
17240 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
17250 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17260 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12700}.**.** T
17270 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
17280 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
17290 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
172a0 20 6e 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65   name.** is give
172b0 6e 20 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d  n by the filenam
172c0 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  e argument..** T
172d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
172e0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
172f0 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20  ted as UTF-8.** 
17300 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  for [sqlite3_ope
17310 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
17320 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64  3_open_v2()] and
17330 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e   as UTF-16.** in
17340 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
17350 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
17360 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
17370 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20  * An [sqlite3*] 
17380 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
17390 79 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  y returned in *p
173a0 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20  pDb, even.** if 
173b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
173c0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
173d0 74 69 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74  tion is if SQLit
173e0 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74  e is unable.** t
173f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
17400 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
17410 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20  qlite3] object, 
17420 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62  a NULL will.** b
17430 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
17440 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
17450 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
17460 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
17470 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  t..** If the dat
17480 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
17490 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
174a0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
174b0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f  , then [SQLITE_O
174c0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
174d0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a   Otherwise an.**
174e0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
174f0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a  eturned.  The.**
17500 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
17510 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17520 65 72 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75  errmsg16()]  rou
17530 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
17540 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
17550 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
17560 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
17570 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
17580 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
17590 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
175a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
175b0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71   UTF-8 if.** [sq
175c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
175d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
175e0 32 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61  2()] is called a
175f0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
17600 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
17610 6f 72 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65  order if [sqlite
17620 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
17630 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
17640 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
17650 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
17660 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
17670 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
17680 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73  ated with the [s
17690 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
176a0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
176b0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ed by passing it
176c0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
176d0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
176e0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
176f0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
17700 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
17710 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
17720 77 6f 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69  works like [sqli
17730 74 65 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20  te3_open()] .** 
17740 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
17750 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
17760 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
17770 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
17780 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
17790 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
177a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
177b0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
177c0 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20  r can be.** one 
177d0 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  of:.**.** <ol>.*
177e0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
177f0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a  OPEN_READONLY].*
17800 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
17810 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a  OPEN_READWRITE].
17820 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
17830 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
17840 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
17850 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e  CREATE].** </ol>
17860 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
17870 20 76 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65   value opens the
17880 20 64 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f   database read-o
17890 6e 6c 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20  nly. .** If the 
178a0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
178b0 74 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69  t previously exi
178c0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
178d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
178e0 20 73 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f   second option o
178f0 70 65 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  pens.** the data
17900 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
17910 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
17920 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
17930 64 69 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20  ding only if.** 
17940 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
17950 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20  rite protected. 
17960 20 49 6e 20 65 69 74 68 65 72 20 63 61 73 65 20   In either case 
17970 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
17980 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
17990 73 74 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69  st or an error i
179a0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
179b0 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a   third option.**
179c0 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
179d0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
179e0 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20  and writing and 
179f0 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74  creates it if it
17a00 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72   does.** not alr
17a10 65 61 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54  eady exist..** T
17a20 68 65 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73  he third options
17a30 20 69 73 20 62 65 68 61 76 69 6f 72 20 74 68 61   is behavior tha
17a40 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
17a50 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
17a60 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  en()].** and [sq
17a70 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
17a80 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
17a90 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
17aa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17ab0 29 5d 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  )] is not one of
17ac0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
17ad0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
17ae0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
17af0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
17b00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
17b10 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
17b20 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72  ry:", then an pr
17b30 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f  ivate.** in-memo
17b40 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
17b50 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
17b60 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
17b70 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61   in-memory.** da
17b80 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
17b90 73 68 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  sh when the data
17ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17bb0 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
17bc0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  re.** version of
17bd0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61   SQLite might ma
17be0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
17bf0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
17c00 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62  enames.** that b
17c10 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
17c20 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74  " character.  It
17c30 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
17c40 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20  that .** when a 
17c50 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
17c60 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65  e really does be
17c70 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20  gin with.** ":" 
17c80 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20  that you prefix 
17c90 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
17ca0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b  h a pathname lik
17cb0 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f  e "./" to.** avo
17cc0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
17cd0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
17ce0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
17cf0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
17d00 72 69 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79  rivate temporary
17d10 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
17d20 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
17d30 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
17d40 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
17d50 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
17d60 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
17d70 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
17d80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17d90 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
17da0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
17db0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17dc0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
17dd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
17de0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
17df0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
17e00 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
17e10 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74  g system .** int
17e20 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
17e30 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
17e40 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
17e50 73 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  se.  If the.** f
17e60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
17e70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
17e80 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
17e90 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
17ea0 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73  .** object is us
17eb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
17ec0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
17ed0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
17ee0 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
17ef0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
17f00 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69  ment.** of [sqli
17f10 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
17f20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
17f30 28 29 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d  ()] must be UTF-
17f40 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
17f50 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
17f60 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
17f70 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
17f80 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
17f90 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
17fa0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
17fb0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
17fc0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
17fd0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  them into.** [sq
17fe0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72  lite3_open()] or
17ff0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
18000 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
18010 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
18020 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  12701} The [sqli
18030 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
18040 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
18050 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18060 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
18070 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
18080 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20  create a new.** 
18090 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
180a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
180b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
180c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64  *          the d
180d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76  atabase file giv
180e0 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73  en in their firs
180f0 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
18100 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20  ** {F12702} The 
18110 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
18120 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
18130 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20   as UTF-8.**    
18140 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74        for [sqlit
18150 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
18160 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18170 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  )] and as UTF-16
18180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
18190 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
181a0 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74  order for [sqlit
181b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
181c0 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73  .** {F12703} A s
181d0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
181e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
181f0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
18200 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a  e3_open16()], .*
18210 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
18220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
18230 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74  ] writes a point
18240 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
18250 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
18260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e  e connection] in
18270 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20  to *ppDb..**.** 
18280 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71  {F12704} The [sq
18290 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
182a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
182b0 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
182c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
182d0 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
182e0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
182f0 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73  _OK] upon succes
18300 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  s,.**          o
18310 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
18320 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
18330 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
18340 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66  {F12706} The def
18350 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
18360 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
18370 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
18380 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
18390 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
183a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
183b0 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20  n_v2()] will be 
183c0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
183d0 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c  2707} The defaul
183e0 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
183f0 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
18400 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
18410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18420 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
18430 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a  will be UTF-16..
18440 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54  **.** {F12709} T
18450 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
18460 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  (F,D)] interface
18470 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
18480 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
18490 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
184a0 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74  ,D,G,0)] where t
184b0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69  he G parameter i
184c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
184d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
184e0 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50  RITE]|[SQLITE_OP
184f0 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a  EN_CREATE]..**.*
18500 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68  * {F12711} If th
18510 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
18520 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
18530 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
18540 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
18550 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
18560 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
18570 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64  ONLY] then the d
18580 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
18590 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  d.**          fo
185a0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a  r reading only..
185b0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49  **.** {F12712} I
185c0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
185d0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
185e0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
185f0 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
18600 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
18610 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
18620 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20  READWRITE] then 
18630 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
18640 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
18650 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77     reading and w
18660 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
18670 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69  le, or for readi
18680 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a  ng only if the.*
18690 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20  *          file 
186a0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
186b0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
186c0 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a  ing system..**.*
186d0 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68  * {F12713} If th
186e0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
186f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
18700 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74  2(F,D,G,V)] omit
18710 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
18720 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
18730 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
18740 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
18750 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
18760 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
18770 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
18780 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
18790 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66  *.** {F12714} If
187a0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
187b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
187c0 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n(v2(F,D,G,V)] c
187d0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
187e0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
187f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
18800 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
18810 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
18820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
18830 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74  viously exist, t
18840 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hen an attempt i
18850 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65  s made to create
18860 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18870 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
18880 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
18890 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20  {F12717} If the 
188a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
188b0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
188c0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
188d0 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
188e0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
188f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
18900 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
18910 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a  n an private,.**
18920 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
18930 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  ral, in-memory d
18940 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
18950 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
18960 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20  ction..**       
18970 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
18980 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
18990 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
189a0 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
189b0 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
189c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
189d0 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
189e0 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c  2719} If the fil
189f0 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72  ename is NULL or
18a00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
18a10 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
18a20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
18a30 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20  hemeral on-disk 
18a40 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
18a50 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20   created..**    
18a60 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
18a70 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
18a80 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
18a90 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
18aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
18ab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18ac0 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
18ad0 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61  {F12721} The [da
18ae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18af0 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a  n] created by .*
18b00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18b10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
18b20 47 2c 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74  G,V)] will use t
18b30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
18b40 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
18b50 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62  ect identified b
18b60 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65  y the V paramete
18b70 72 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  r, or.**        
18b80 20 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73    the default [s
18b90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
18ba0 63 74 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c  ct is V is a NUL
18bb0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
18bc0 20 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b 64   {F12723} Two [d
18bd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18be0 6f 6e 20 7c 20 64 61 74 61 62 61 73 65 20 63 6f  on | database co
18bf0 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
18c00 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
18c10 61 63 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ache.**         
18c20 20 69 66 20 62 6f 74 68 20 77 65 72 65 20 6f 70   if both were op
18c30 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ened with the sa
18c40 6d 65 20 56 46 53 0a 2a 2a 20 20 20 20 20 20 20  me VFS.**       
18c50 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
18c60 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
18c70 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63  cache | shared c
18c80 61 63 68 65 20 6d 6f 64 65 20 77 61 73 20 65 6e  ache mode was en
18c90 61 62 6c 65 64 5d 20 61 6e 64 0a 2a 2a 20 20 20  abled] and.**   
18ca0 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66         if both f
18cb0 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65  ilenames compare
18cc0 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d   equal using mem
18cd0 63 6d 70 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  cmp().**        
18ce0 20 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 62    after having b
18cf0 65 65 6e 20 70 72 6f 63 65 73 73 65 64 20 62 79  een processed by
18d00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
18d10 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  s | xFullPathnam
18d20 65 5d 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  e] method of.** 
18d30 20 20 20 20 20 20 20 20 20 74 68 65 20 56 46 53           the VFS
18d40 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ..**.*/.int sqli
18d50 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
18d60 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
18d70 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
18d80 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
18d90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
18da0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
18db0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
18dc0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
18dd0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
18de0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
18df0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
18e00 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
18e10 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
18e20 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
18e30 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
18e40 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
18e50 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
18e60 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
18e70 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
18e80 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
18e90 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
18ea0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
18eb0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
18ec0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
18ed0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
18ee0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
18ef0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
18f00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
18f10 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
18f20 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
18f30 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
18f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
18f50 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
18f60 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a  ssages {F12800}.
18f70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18f80 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
18f90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
18fa0 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51  e numeric.** [SQ
18fb0 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
18fc0 20 63 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54   code] or [SQLIT
18fd0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
18fe0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
18ff0 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ode].** for the 
19000 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
19010 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
19020 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
19030 0a 2a 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65  .** with [sqlite
19040 33 5d 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20  3] handle 'db'. 
19050 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
19060 61 6c 6c 20 66 61 69 6c 65 64 20 62 75 74 20 74  all failed but t
19070 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
19080 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
19090 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
190a0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
190b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  te3_errcode().**
190c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
190d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
190e0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
190f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
19100 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
19110 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
19120 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
19130 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
19140 74 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46  ther UTF8 or UTF
19150 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
19160 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
19170 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
19180 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
19190 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
191a0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
191b0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
191c0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 77 69 74  eed to worry wit
191d0 68 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  h freeing the re
191e0 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
191f0 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
19200 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
19210 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
19220 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
19230 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
19240 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
19250 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
19260 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
19270 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  NTS:.**.** {F128
19280 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
19290 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74  _errcode(D)] int
192a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
192b0 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20  he numeric.**   
192c0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
192d0 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  K | result code]
192e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
192f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
19300 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
19310 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20 20  sult code].**   
19320 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6d         for the m
19330 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 66 61 69  ost recently fai
19340 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
19350 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
19360 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 5b            with [
19370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19380 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
19390 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  12803} The [sqli
193a0 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61  te3_errmsg(D)] a
193b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
193c0 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20  sg16(D)].**     
193d0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
193e0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
193f0 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68 61  anguage text tha
19400 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20  t describes.**  
19410 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72 6f          the erro
19420 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20  r in the mostly 
19430 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20  recently failed 
19440 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a  interface call,.
19450 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f  **          enco
19460 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55 54  ded as either UT
19470 46 38 20 6f 72 20 55 54 46 31 36 20 72 65 73 70  F8 or UTF16 resp
19480 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
19490 7b 46 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {F12807} The str
194a0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
194b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
194c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
194d0 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
194e0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
194f0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
19500 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
19510 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
19520 46 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  F12808} Calls to
19530 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
19540 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
19550 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
19560 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
19570 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
19580 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
19590 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
195a0 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
195b0 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
195c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
195d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
195e0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
195f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
19600 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
19610 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
19620 20 7b 46 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {F12809} Interf
19630 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
19640 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
19650 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
19660 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
19670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
19680 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
19690 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
196a0 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
196b0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
196c0 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
196d0 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
196e0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
196f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
19700 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
19710 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
19720 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
19730 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
19740 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
19750 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
19760 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
19770 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
19780 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
19790 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
197a0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
197b0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
197c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
197d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
197e0 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a  ject {F13000}.**
197f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
19800 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
19810 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
19820 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
19830 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
19840 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
19850 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
19860 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 0a  tatement.  This.
19870 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  ** object is var
19880 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
19890 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
198a0 65 6d 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20  ement" or a .** 
198b0 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
198c0 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
198d0 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
198e0 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20  nt"..** .** The 
198f0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
19900 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
19910 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
19920 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
19930 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
19940 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
19950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19960 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
19970 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
19980 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
19990 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
199a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 75 73 69  t parameters usi
199b0 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
199c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
199d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69  sqlite3_bind_* i
199e0 6e 74 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c  nterfaces]..** <
199f0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
19a00 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
19a10 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
19a20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
19a30 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
19a40 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
19a50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
19a60 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
19a70 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
19a80 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
19a90 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
19aa0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
19ab0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
19ac0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
19ad0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
19ae0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
19af0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
19b00 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
19b10 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
19b20 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
19b30 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
19b40 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
19b50 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
19b60 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
19b70 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
19b80 69 6d 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a  imits {F12760}.*
19b90 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
19ba0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
19bb0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
19bc0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
19bd0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
19be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
19bf0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
19c00 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
19c10 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
19c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19c30 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
19c40 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
19c50 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
19c60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
19c70 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
19c80 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
19c90 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
19ca0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
19cb0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
19cc0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
19cd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
19ce0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
19cf0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
19d00 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
19d10 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19d20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
19d30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
19d40 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
19d50 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
19d60 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
19d70 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
19d80 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
19d90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
19da0 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72  Z there is a har
19db0 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64  d upper.** bound
19dc0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
19dd0 65 2d 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63  e-time C-preproc
19de0 65 73 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20  ess macro named 
19df0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a  SQLITE_MAX_XYZ..
19e00 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
19e10 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
19e20 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
19e30 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
19e40 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
19e50 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
19e60 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
19e70 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
19e80 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
19e90 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
19ea0 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
19eb0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
19ec0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
19ed0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
19ee0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
19ef0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
19f00 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
19f10 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
19f20 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
19f30 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
19f40 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
19f50 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
19f60 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
19f70 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
19f80 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61  bbrowser that ha
19f90 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
19fa0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
19fb0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
19fc0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
19fd0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
19fe0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
19ff0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1a000 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1a010 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1a020 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1a030 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1a040 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1a050 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1a060 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1a070 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1a080 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1a090 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1a0a0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1a0b0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1a0c0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1a0d0 20 61 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f   attach.  Develo
1a0e0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1a0f0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1a100 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a110 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1a120 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1a130 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1a140 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1a150 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1a160 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1a170 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1a180 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1a190 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1a1a0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1a1b0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1a1c0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1a1d0 61 63 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ace is currently
1a1e0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1a1f0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
1a200 73 75 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68  subject.** to ch
1a210 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20  ange or removal 
1a220 77 69 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f  without prior no
1a230 74 69 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tice..**.** INVA
1a240 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1a250 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73  12762} A success
1a260 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1a270 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1a280 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a  )] where V is.**
1a290 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69            positi
1a2a0 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ve changes the.*
1a2b0 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74  *          limit
1a2c0 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1a2d0 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b  construct C in [
1a2e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a2f0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
1a300 20 20 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72     to the lesser
1a310 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61   of V and the ha
1a320 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  rd upper bound o
1a330 6e 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20  n the size.**   
1a340 20 20 20 20 20 20 20 6f 66 20 43 20 74 68 61 74         of C that
1a350 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69   is set at compi
1a360 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  le-time..**.** {
1a370 46 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73  F12766} A succes
1a380 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1a390 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1a3a0 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e  V)] where V is n
1a3b0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
1a3c0 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73      leaves the s
1a3d0 74 61 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73  tate of [databas
1a3e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1a3f0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
1a400 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63 63   {F12769} A succ
1a410 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1a420 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
1a430 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
1a440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
1a450 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
1a460 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1a470 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a  construct C in.*
1a480 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64  *          in [d
1a490 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a4a0 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73 20  on] D as it was 
1a4b0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c  prior to the cal
1a4c0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1a4d0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
1a4e0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
1a4f0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
1a500 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1a510 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
1a520 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45  s {F12790}.** KE
1a530 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
1a540 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20  ategory} {limit 
1a550 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a  categories}.** .
1a560 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1a570 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
1a580 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b  s aspects of a [
1a590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a5a0 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e  ion].** that can
1a5b0 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73   be limited in s
1a5c0 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ize by calls to 
1a5d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1a5e0 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e  ]..** The meanin
1a5f0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
1a600 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20  s limits are as 
1a610 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a620 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
1a630 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1a640 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1a650 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1a660 6e 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ny.** string or 
1a670 62 6c 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f  blob or table ro
1a680 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
1a690 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1a6a0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1a6b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a6c0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1a6d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1a6e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1a6f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1a700 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a710 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a720 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1a730 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1a740 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1a750 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
1a760 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  ECT or the maxim
1a770 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1a780 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1a790 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
1a7a0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
1a7b0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
1a7c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a7d0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1a7e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a7f0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1a800 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1a810 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1a820 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
1a830 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1a840 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
1a850 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a860 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a870 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
1a880 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
1a890 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
1a8a0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a8b0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
1a8c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1a8d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
1a8e0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
1a8f0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1a900 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
1a910 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
1a920 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1a930 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1a940 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1a950 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
1a960 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1a970 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
1a980 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
1a990 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
1a9a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1a9b0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1a9c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1a9d0 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68  number of attach
1a9e0 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64  ed databases.</d
1a9f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1aa00 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1aa10 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1aa20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1aa30 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1aa40 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1aa50 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45  ment to the LIKE
1aa60 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72   or.** GLOB oper
1aa70 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ators.</dd>.**.*
1aa80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1aa90 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1aaa0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1aab0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1aac0 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
1aad0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1aae0 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
1aaf0 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a  e bound.</dd>.**
1ab00 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1ab10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1ab20 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1ab30 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1ab40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1ab50 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1ab60 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1ab70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1ab80 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1ab90 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1aba0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1abb0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1abc0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1abd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1abe0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1abf0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1ac00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ac10 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1ac20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1ac30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1ac40 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1ac50 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1ac60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ac70 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1ac80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ac90 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1aca0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1acb0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1acc0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1acd0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1ace0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1acf0 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    9../*.** CAPI3
1ad00 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
1ad10 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1ad20 7b 46 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13010}.**.** T
1ad30 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
1ad40 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
1ad50 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
1ad60 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
1ad70 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
1ad80 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
1ad90 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a   routines. .**.*
1ada0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1adb0 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20  ment "db" is an 
1adc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1add0 74 69 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e  tion] .** obtain
1ade0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20  ed from a prior 
1adf0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1ae00 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1ae10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a  e3_open_v2()].**
1ae20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1ae30 6e 31 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20  n16()]. .** The 
1ae40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1ae50 22 7a 53 71 6c 22 20 69 73 20 74 68 65 20 73 74  "zSql" is the st
1ae60 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1ae70 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
1ae80 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
1ae90 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
1aea0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1aeb0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
1aec0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
1aed0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 73   interfaces uses
1aee0 20 55 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74   UTF-8 and sqlit
1aef0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
1af00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1af10 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
1af20 20 55 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a   UTF-16. {END}.*
1af30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74  *.** If the nByt
1af40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1af50 73 73 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c  ss.** than zero,
1af60 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
1af70 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
1af80 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1af90 6f 72 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20  or..** If nByte 
1afa0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1afb0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
1afc0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1afd0 66 20 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64  f .** bytes read
1afe0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
1aff0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
1b000 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
1b010 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
1b020 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
1b030 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
1b040 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
1b050 72 20 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79  r or .** the nBy
1b060 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
1b070 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
1b080 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
1b090 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
1b0a0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
1b0b0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
1b0c0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
1b0d0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
1b0e0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
1b0f0 74 61 67 65 20 74 6f 20 62 65 20 68 61 64 20 62  tage to be had b
1b100 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1b110 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1b120 74 20 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  t .** is equal t
1b130 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
1b140 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
1b150 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
1b160 6c 75 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74  luding</i> .** t
1b170 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
1b180 72 20 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a  r bytes.{END}.**
1b190 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  .** *pzTail is m
1b1a0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1b1b0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70  the first byte p
1b1c0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1b1d0 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20  he.** first SQL 
1b1e0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1b1f0 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
1b200 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20  es only compile 
1b210 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61  the first.** sta
1b220 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
1b230 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
1b240 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77  ft pointing to w
1b250 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75  hat remains.** u
1b260 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
1b270 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74   *ppStmt is left
1b280 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
1b290 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
1b2a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1b2b0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
1b2c0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
1b2d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72  te3_step()].  Or
1b2e0 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
1b2f0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1b300 73 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c  s.** set to NULL
1b310 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1b320 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1b330 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1b340 75 74 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70  ut.** is and emp
1b350 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
1b360 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1b370 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1b380 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d  ULL..** {U13018}
1b390 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1b3a0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1b3b0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1b3c0 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ng the.** compil
1b3d0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1b3e0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
1b3f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1b400 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1b410 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1b420 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
1b430 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1b440 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1b450 69 73 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f  ise an .** [erro
1b460 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1b470 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1b480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b490 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
1b4a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
1b4b0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
1b4c0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
1b4d0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
1b4e0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
1b4f0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1b500 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
1b510 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1b520 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
1b530 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
1b540 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
1b550 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1b560 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1b570 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1b580 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1b590 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1b5a0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1b5b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1b5c0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
1b5d0 20 74 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69   text. {END} Thi
1b5e0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
1b5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
1b600 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
1b610 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
1b620 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
1b630 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1b640 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
1b650 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1b660 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1b670 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1b680 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1b690 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1b6a0 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1b6b0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1b6c0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1b6d0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1b6e0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1b6f0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1b700 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
1b710 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
1b720 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
1b730 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
1b740 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
1b750 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
1b760 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
1b770 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1b780 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
1b790 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
1b7a0 79 20 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20  y behavior, .** 
1b7b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1b7c0 69 73 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  is now a fatal e
1b7d0 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a  rror.  Calling.*
1b7e0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1b7f0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
1b800 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
1b810 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
1b820 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
1b830 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1b840 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
1b850 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
1b860 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
1b870 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
1b880 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
1b890 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f  urn. {END}.** </
1b8a0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1b8b0 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
1b8c0 6f 63 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c  occurs, .** [sql
1b8d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1b8e0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
1b8f0 74 68 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a  the detailed .**
1b900 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1b910 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1b920 72 20 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68  r codes]. .** Th
1b930 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1b940 72 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69  r was that [sqli
1b950 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
1b960 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
1b970 67 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  generic.** [SQLI
1b980 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
1b990 20 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f   code and you wo
1b9a0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1b9b0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1b9c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
1b9d0 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  set()] in order 
1b9e0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1b9f0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1ba00 74 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20  the problem..** 
1ba10 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
1ba20 65 70 61 72 65 20 69 6e 74 65 72 66 61 63 65 73  epare interfaces
1ba30 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1ba40 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1ba50 65 72 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75  error is.** retu
1ba60 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1ba70 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
1ba80 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ol>.**.** INVARI
1ba90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1baa0 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  011} The [sqlite
1bab0 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
1bac0 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1bad0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1bae0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1baf0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
1bb00 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
1bb10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
1bb20 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
1bb30 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
1bb40 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  TF-8..**.** {F13
1bb50 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  012} The [sqlite
1bb60 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a  3_prepare16(db,z
1bb70 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
1bb80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1bb90 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1bba0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1bbb0 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1bbc0 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1bbd0 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1bbe0 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1bbf0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1bc00 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1bc10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  er..**.** {F1301
1bc20 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
1bc30 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1bc40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1bc50 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
1bc60 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1bc70 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1bc80 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1bc90 72 6f 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78  ro, then SQL tex
1bca0 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
1bcb0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
1bcc0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1bcd0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1bce0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
1bcf0 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
1bd00 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1bd10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bd20 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1bd30 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1bd40 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1bd50 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
1bd60 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
1bd70 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
1bd80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1bd90 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
1bda0 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
1bdb0 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  F13015} In [sqli
1bdc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1bdd0 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
1bde0 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
1bdf0 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
1be00 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
1be10 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1be20 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
1be30 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1be40 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
1be50 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
1be60 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1be70 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1be80 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
1be90 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
1bea0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1beb0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1bec0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
1bed0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1bee0 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
1bef0 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
1bf00 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
1bf10 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
1bf20 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75  ** {F13016} A su
1bf30 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1bf40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bf50 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
1bf60 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
1bf70 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
1bf80 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
1bf90 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
1bfa0 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
1bfb0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1bfc0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1bfd0 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
1bfe0 74 65 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20  ter to NULL.**  
1bff0 20 20 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20          if zSql 
1c000 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
1c010 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
1c020 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
1c030 74 73 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  ts. .**.** {F130
1c040 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1c050 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1c060 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1c070 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1c080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1c090 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1c0a0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1c0b0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1c0c0 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
1c0d0 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1c0e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1c0f0 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1c100 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1c110 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1c120 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1c130 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1c140 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1c150 51 4c 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20  QLITE_OK]).**   
1c160 20 20 20 20 20 20 20 69 74 20 66 69 72 73 74 20         it first 
1c170 73 65 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20  sets *ppStmt to 
1c180 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1c190 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
1c1a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1c1b0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1c1c0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1c1d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1c1e0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1c1f0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1c200 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1c210 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1c220 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1c230 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1c240 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1c250 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1c260 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1c270 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1c280 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1c290 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1c2a0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1c2b0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1c2c0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1c2d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c2e0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1c2f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1c300 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1c310 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1c320 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1c330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1c340 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1c350 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1c360 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1c370 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1c380 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1c390 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1c3a0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1c3b0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1c3c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1c3d0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1c3e0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1c3f0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1c400 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1c410 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1c420 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1c430 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1c440 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1c450 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1c460 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1c470 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1c480 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1c490 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1c4a0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1c4b0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1c4c0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1c4d0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1c4e0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1c4f0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1c500 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1c510 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1c520 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1c530 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1c540 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1c550 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1c560 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1c570 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1c580 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1c590 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1c5a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1c5b0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1c5c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1c5d0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1c5e0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1c5f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1c600 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1c610 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1c620 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1c630 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1c640 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1c650 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1c660 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1c670 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1c680 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1c690 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1c6a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a  ../*.** CAPIREF:
1c6b0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
1c6c0 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30  ement SQL {F1310
1c6d0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
1c6e0 74 65 72 66 61 63 65 20 20 63 61 6e 20 62 65 20  terface  can be 
1c6f0 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1c700 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1c710 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1c720 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1c730 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1c740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1c750 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1c760 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31  S:.**.** {F13101
1c770 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1c780 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1c790 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1c7a0 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1c7b0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1c7c0 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1c7d0 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1c7e0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1c7f0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1c800 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1c810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1c820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1c830 76 32 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  v2()],.**       
1c840 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
1c850 5f 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e  _sql()] function
1c860 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c870 65 72 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20  er to a.**      
1c880 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
1c890 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  ted string conta
1c8a0 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65  ining a UTF-8 re
1c8b0 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ndering.**      
1c8c0 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69      of the origi
1c8d0 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  nal SQL statemen
1c8e0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32  t..**.** {F13102
1c8f0 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
1c900 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
1c910 73 73 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20  ssed as .**     
1c920 20 20 20 20 20 74 68 65 20 61 6e 20 61 72 67 75       the an argu
1c930 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1c940 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
1c950 69 6c 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  iled.**         
1c960 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1c970 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1c980 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
1c990 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c9a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
1c9b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c9c0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1c9d0 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
1c9e0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1c9f0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33  r..**.** {F13103
1ca00 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1ca10 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1ca20 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1ca30 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1ca40 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1ca50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1ca60 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1ca70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1ca80 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1ca90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1caa0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1cab0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1cac0 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d  CAPI3REF:  Dynam
1cad0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1cae0 75 65 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30  ue Object  {F150
1caf0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
1cb00 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1cb10 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1cb20 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1cb30 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1cb40 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1cb50 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1cb60 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1cb70 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1cb80 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1cb90 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1cba0 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ble..** SQLite u
1cbb0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1cbc0 6e 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ng for the value
1cbd0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a  s it stores.  .*
1cbe0 2a 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  * Values stored 
1cbf0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1cc00 20 6f 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a   objects can be.
1cc10 2a 2a 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  ** be integers, 
1cc20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1cc30 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1cc40 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1cc50 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1cc60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1cc70 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1cc80 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1cc90 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1cca0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1ccb0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1ccc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1ccd0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1cce0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1ccf0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1cd00 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1cd10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1cd20 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1cd30 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1cd40 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1cd50 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1cd60 63 69 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68  cifies .** wheth
1cd70 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1cd80 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1cd90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1cda0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1cdb0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1cdc0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1cdd0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1cde0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1cdf0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1ce00 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1ce10 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1ce20 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1ce30 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1ce40 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1ce50 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1ce60 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1ce70 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1ce80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1ce90 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1cea0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1ceb0 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41  ith SQLITE_THREA
1cec0 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68  DSAFE=0 and with
1ced0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1cee0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1cef0 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  g 0).** then the
1cf00 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1cf10 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
1cf20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1cf30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1cf40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1cf50 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a  and they can be.
1cf60 2a 2a 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  ** used intercha
1cf70 6e 67 65 61 62 6c 65 2e 20 20 48 6f 77 65 76 65  ngeable.  Howeve
1cf80 72 2c 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  r, for maximum c
1cf90 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1cfa0 69 74 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65  it.** is recomme
1cfb0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1cfc0 61 74 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20  ations make the 
1cfd0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1cfe0 65 65 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70  een.** between p
1cff0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1d000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1d010 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1d020 76 65 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61  ven if.** they a
1d030 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  re single thread
1d040 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1d050 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1d060 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1d070 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1d080 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1d090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1d0a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
1d0b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 7c 20 61  ate_function | a
1d0c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1d0d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1d0e0 5d 0a 2a 2a 20 61 72 65 20 70 72 6f 74 65 63 74  ].** are protect
1d0f0 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1d100 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1d110 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1d120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1d130 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1d140 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1d150 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1d160 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1d170 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1d180 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1d190 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1d1a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1d1b0 5f 76 61 6c 75 65 28 29 5d 2e 20 20 0a 2a 2a 20  _value()].  .** 
1d1c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
1d1d0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
1d1e0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
1d1f0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
1d200 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1d210 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1d220 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
1d230 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1d240 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
1d250 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
1d260 49 33 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63  I3REF:  SQL Func
1d270 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1d280 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a  ect {F16001}.**.
1d290 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
1d2a0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
1d2b0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
1d2c0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
1d2d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
1d2e0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
1d2f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1d300 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20  ite3_context.** 
1d310 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73  object is always
1d320 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d330 20 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   to .** [sqlite3
1d340 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1d350 20 7c 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64   | application-d
1d360 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1d370 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1d380 70 6c 69 63 61 74 69 6f 6e 65 64 2d 64 65 66 69  plicationed-defi
1d390 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1d3a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1d3b0 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
1d3c0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
1d3d0 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 0a  h into calls to.
1d3e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1d3f0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1d400 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1d410 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1d420 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 0a 2a 2a  e_context()],.**
1d430 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1d440 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1d450 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1d460 61 6e 64 6c 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71  andle()],.** [sq
1d470 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
1d480 61 28 29 5d 2c 20 61 6e 64 2f 6f 72 20 5b 73 71  a()], and/or [sq
1d490 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1d4a0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1d4b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1d4c0 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1d4d0 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1d4e0 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69  CAPI3REF:  Bindi
1d4f0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1d500 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1d510 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F13500}.**.** 
1d520 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e  In the SQL strin
1d530 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  gs input to [sql
1d540 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d550 29 5d 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61  )] and its.** va
1d560 72 69 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73  riants, literals
1d570 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 20   may be replace 
1d580 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
1d590 6e 20 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73  n one.** of thes
1d5a0 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1d5b0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1d5c0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1d5d0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1d5e0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1d5f0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1d600 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1d610 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1d620 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1d630 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1d640 61 6c 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61  al,.** VVV alpha
1d650 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1d660 65 72 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  er name..** The 
1d670 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20  values of these 
1d680 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1d690 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1d6a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a  rameter names".*
1d6b0 2a 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  * or "SQL parame
1d6c0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1d6d0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1d6e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1d6f0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1d700 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
1d710 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1d720 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
1d730 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1d740 20 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20   always.** is a 
1d750 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1d760 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1d770 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
1d780 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
1d790 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1d7a0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68  its variants. Th
1d7b0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
1d7c0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1d7d0 78 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  x of the paramet
1d7e0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68  er to be set. Th
1d7f0 65 0a 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d  e.** first param
1d800 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1d810 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
1d820 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1d830 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
1d840 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
1d850 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
1d860 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
1d870 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
1d880 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
1d890 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1d8a0 63 65 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65  ce. .** The inde
1d8b0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
1d8c0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
1d8d0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
1d8e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
1d8f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1d900 65 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  e()] API if desi
1d910 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
1d920 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1d930 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1d940 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1d950 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
1d960 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1d970 20 61 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65   and the compile
1d980 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74  -time.** paramet
1d990 65 72 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41  er SQLITE_MAX_VA
1d9a0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64  RIABLE_NUMBER (d
1d9b0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1d9c0 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  9)..**.** The th
1d9d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
1d9e0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
1d9f0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
1da00 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f  er..**.** In tho
1da10 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
1da20 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1da30 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1da40 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
1da50 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1da60 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1da70 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1da80 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1da90 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
1daa0 74 65 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68  tes</u>.** in th
1dab0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1dac0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1dad0 63 74 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68  cters. .** If th
1dae0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1daf0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1db00 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1db10 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
1db20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1db30 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
1db40 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1db50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
1db60 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
1db70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1db80 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
1db90 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
1dba0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1dbb0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
1dbc0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
1dbd0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
1dbe0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
1dbf0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
1dc00 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1dc10 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
1dc20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
1dc30 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
1dc40 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
1dc50 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
1dc60 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
1dc70 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
1dc80 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
1dc90 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
1dca0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1dcb0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
1dcc0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1dcd0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
1dce0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
1dcf0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
1dd00 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
1dd10 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
1dd20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
1dd30 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
1dd40 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
1dd50 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
1dd60 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
1dd70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1dd80 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
1dd90 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
1dda0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
1ddb0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
1ddc0 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72  th zeros.  A zer
1ddd0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1dde0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1ddf0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1de00 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1de10 69 74 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  it size) while i
1de20 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1de30 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1de40 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1de50 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1de60 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1de70 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1de80 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1de90 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  tten using .** [
1dea0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1deb0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c  n | increment BL
1dec0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1ded0 2e 20 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20  . A negative.** 
1dee0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
1def0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
1df00 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
1df10 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
1df20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1df30 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1df40 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
1df50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1df60 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
1df70 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
1df80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1df90 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
1dfa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1dfb0 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
1dfc0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
1dfd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
1dfe0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
1dff0 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
1e000 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1e010 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1e020 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1e030 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1e040 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1e050 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
1e060 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
1e070 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
1e080 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
1e090 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
1e0a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
1e0b0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
1e0c0 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
1e0d0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
1e0e0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
1e0f0 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
1e100 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
1e110 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
1e120 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1e130 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
1e140 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
1e150 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
1e160 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
1e170 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
1e180 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
1e190 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
1e1a0 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
1e1b0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
1e1c0 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
1e1d0 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
1e1e0 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
1e1f0 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
1e200 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
1e210 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
1e220 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
1e230 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
1e240 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1e250 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
1e260 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
1e270 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
1e280 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
1e290 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1e2a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1e2b0 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1e2c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e2d0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1e2e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1e2f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1e300 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
1e310 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1e320 31 33 35 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13506} The [sqli
1e330 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51  te3_prepare | SQ
1e340 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
1e350 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
1e360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b  .**          tok
1e370 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  ens of the forms
1e380 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
1e390 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
1e3a0 64 20 22 40 56 56 56 22 0a 2a 2a 20 20 20 20 20  d "@VVV".**     
1e3b0 20 20 20 20 20 61 73 20 53 51 4c 20 70 61 72 61       as SQL para
1e3c0 6d 65 74 65 72 73 2c 20 77 68 65 72 65 20 4e 4e  meters, where NN
1e3d0 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
1e3e0 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
1e3f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69 67  .**          dig
1e400 69 74 73 20 61 6e 64 20 77 68 65 72 65 20 56 56  its and where VV
1e410 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
1e420 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
1e430 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c   .**          al
1e440 70 68 61 6e 75 6d 65 72 69 63 20 63 68 61 72 61  phanumeric chara
1e450 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70  cters or "::" op
1e460 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65  tionally followe
1e470 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1e480 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69   a string contai
1e490 6e 69 6e 67 20 6e 6f 20 73 70 61 63 65 73 20 61  ning no spaces a
1e4a0 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74  nd contained wit
1e4b0 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e  hin parentheses.
1e4c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20  .**.** {F13509} 
1e4d0 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75  The initial valu
1e4e0 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  e of an SQL para
1e4f0 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a  meter is NULL..*
1e500 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68  *.** {F13512} Th
1e510 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
1e520 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
1e530 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68  is one larger th
1e540 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  an the.**       
1e550 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78     largest index
1e560 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
1e570 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f  r to the left, o
1e580 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  r 1 if.**       
1e590 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68     the "?" is th
1e5a0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1e5b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1e5c0 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64  {F13515} The ind
1e5d0 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20  ex of an "?NNN" 
1e5e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1e5f0 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e   the integer NNN
1e600 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d  ..**.** {F13518}
1e610 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
1e620 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c   ":VVV", "$VVV",
1e630 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70   or "@VVV" SQL p
1e640 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
1e650 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
1e660 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   as the index of
1e670 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72   leftmost occurr
1e680 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d  ences of the sam
1e690 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
1e6a0 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20  rameter, or one 
1e6b0 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61  more than the la
1e6c0 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72  rgest index over
1e6d0 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
1e6e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1e6f0 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20  he left if this 
1e700 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  is the first occ
1e710 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20  urrence.**      
1e720 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61      of this para
1e730 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74  meter, or 1 if t
1e740 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d  his is the leftm
1e750 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ost parameter..*
1e760 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54 68  *.** {F13521} Th
1e770 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1e780 72 65 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65  re | SQL stateme
1e790 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69  nt compiler] fai
1e7a0 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  l with.**       
1e7b0 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41     an [SQLITE_RA
1e7c0 4e 47 45 5d 20 65 72 72 6f 72 20 69 66 20 74 68  NGE] error if th
1e7d0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
1e7e0 4c 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  L parameter.**  
1e7f0 20 20 20 20 20 20 20 20 69 73 20 6c 65 73 73 20          is less 
1e800 74 68 61 6e 20 31 20 6f 72 20 67 72 65 61 74 65  than 1 or greate
1e810 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41  r than SQLITE_MA
1e820 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  X_VARIABLE_NUMBE
1e830 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34  R..**.** {F13524
1e840 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
1e850 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1e860 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
1e870 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,V,...)].**     
1e880 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74       associate t
1e890 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20  he value V with 
1e8a0 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
1e8b0 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20  rs having an.** 
1e8c0 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f           index o
1e8d0 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70  f N in the [prep
1e8e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e8f0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37  S..**.** {F13527
1e900 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
1e910 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1e920 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
1e930 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1e940 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f     override prio
1e950 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65  r calls with the
1e960 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20   same values of 
1e970 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  S and N..**.** {
1e980 46 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73  F13530} Bindings
1e990 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20   established by 
1e9a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1e9b0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
1e9c0 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  d(S,...)].**    
1e9d0 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63        persist ac
1e9e0 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ross calls to [s
1e9f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
1ea00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d  ..**.** {F13533}
1ea10 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
1ea20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1ea30 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
1ea40 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1ea50 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
1ea60 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
1ea70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ea80 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1ea90 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
1eaa0 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20  binds the first 
1eab0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  L.**          by
1eac0 74 65 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20  tes of the blob 
1ead0 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  or string pointe
1eae0 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20  d to by V, when 
1eaf0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  L.**          is
1eb00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
1eb10 2a 0a 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e  *.** {F13536} In
1eb20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1eb30 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
1eb40 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20  ,V,L,D)] or.**  
1eb50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1eb60 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
1eb70 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
1eb80 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73  binds characters
1eb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
1eba0 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20  m V through the 
1ebb0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
1ebc0 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e  cter when L is n
1ebd0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
1ebe0 46 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73  F13539} In calls
1ebf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1ec00 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
1ec10 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
1ec20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1ec30 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
1ec40 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1ec50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1ec60 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
1ec70 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
1ec80 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
1ec90 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
1eca0 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69  TE_STATIC], SQLi
1ecb0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
1ecc0 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20  the value V.**  
1ecd0 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20          is held 
1ece0 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61  in static unmana
1ecf0 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77  ged space that w
1ed00 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a  ill not change.*
1ed10 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e  *          durin
1ed20 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
1ed30 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a  f the binding..*
1ed40 2a 0a 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e  *.** {F13542} In
1ed50 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1ed60 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
1ed70 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
1ed80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
1ed90 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
1eda0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
1edb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
1edc0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
1edd0 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
1ede0 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20  the special.**  
1edf0 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74          constant
1ee00 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
1ee10 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65  NT], the routine
1ee20 20 6d 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20   makes a .**    
1ee30 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f        private co
1ee40 70 79 20 6f 66 20 56 20 76 61 6c 75 65 20 62 65  py of V value be
1ee50 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
1ee60 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20  .**.** {F13545} 
1ee70 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
1ee80 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
1ee90 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
1eea0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1eeb0 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
1eec0 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
1eed0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1eee0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
1eef0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
1ef00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
1ef10 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e  *          a fun
1ef20 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e  ction, SQLite in
1ef30 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74  vokes that funct
1ef40 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74  ion to destroy t
1ef50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56  he.**          V
1ef60 20 76 61 6c 75 65 20 61 66 74 65 72 20 69 74 20   value after it 
1ef70 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
1ef80 6e 67 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a  ng the V value..
1ef90 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49  **.** {F13548} I
1efa0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
1efb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1efc0 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20  b(S,N,V,L)] the 
1efd0 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20  value bound.**  
1efe0 20 20 20 20 20 20 20 20 69 73 20 61 20 62 6c 6f          is a blo
1eff0 62 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72  b of L bytes, or
1f000 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62   a zero-length b
1f010 6c 6f 62 20 69 66 20 4c 20 69 73 20 6e 65 67 61  lob if L is nega
1f020 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
1f030 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  551} In calls to
1f040 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1f050 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65  alue(S,N,V)] the
1f060 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a   V argument may.
1f070 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65  **          be e
1f080 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74  ither a [protect
1f090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1f0a0 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a  ] object or an.*
1f0b0 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72  *          [unpr
1f0c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1f0d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
1f0e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1f0f0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
1f100 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1f110 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
1f120 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
1f130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f140 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
1f150 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
1f160 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
1f170 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
1f180 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
1f190 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1f1a0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
1f1b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f1c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
1f1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f1e0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
1f1f0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
1f200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f220 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
1f230 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1f240 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1f250 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1f260 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1f270 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1f280 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
1f290 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1f2a0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1f2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f2c0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
1f2d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
1f2e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1f2f0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
1f300 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
1f310 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f320 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
1f330 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36  Parameters {F136
1f340 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00}.**.** This r
1f350 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
1f360 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
1f370 75 6d 62 65 72 20 6f 66 20 53 51 4c 20 70 61 72  umber of SQL par
1f380 61 6d 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20  ameters.** in a 
1f390 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f3a0 6e 74 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  nt.  SQL paramet
1f3b0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1f3c0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1f3d0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1f3e0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1f3f0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1f400 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1f410 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1f420 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1f430 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1f440 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1f450 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1f460 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
1f470 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
1f480 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1f490 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
1f4a0 72 67 65 73 74 20 70 61 72 61 6d 65 74 65 72 2e  rgest parameter.
1f4b0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  .** For all form
1f4c0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1f4d0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1f4e0 6f 6e 64 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ond to the numbe
1f4f0 72 20 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70  r of.** unique p
1f500 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1f510 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1f520 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 20   ?NNN are used, 
1f530 74 68 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20  there may.** be 
1f540 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
1f550 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1f560 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1f570 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1f580 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1f590 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f5a0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1f5b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f5c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1f5d0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
1f5e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
1f5f0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1f600 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f610 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
1f620 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
1f630 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
1f640 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
1f650 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1f660 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1f670 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1f680 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
1f690 69 66 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  if S.**         
1f6a0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1f6b0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
1f6c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f6d0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1f6e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
1f6f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f700 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
1f710 20 50 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36   Parameter {F136
1f720 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  20}.**.** This r
1f730 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1f740 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1f750 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
1f760 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
1f770 72 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  r in a [prepared
1f780 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1f790 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1f7a0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1f7b0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1f7c0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1f7d0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1f7e0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1f7f0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1f800 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1f810 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1f820 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1f830 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1f840 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1f850 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1f860 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1f870 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1f880 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
1f890 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
1f8a0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
1f8b0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
1f8c0 61 76 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a  ave no name..**.
1f8d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73  ** The first hos
1f8e0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
1f8f0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
1f900 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ot 0..**.** If t
1f910 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75  he value n is ou
1f920 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
1f930 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65   the n-th parame
1f940 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
1f950 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
1f960 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1f970 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1f980 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
1f990 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
1f9a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
1f9b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
1f9c0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
1f9d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
1f9e0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
1f9f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
1fa00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1fa10 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1fa20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1fa30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1fa40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1fa50 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1fa60 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1fa70 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
1fa80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fa90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1faa0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1fab0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d  :.**.** {F13621}
1fac0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
1fad0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1fae0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
1faf0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
1fb00 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
1fb10 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
1fb20 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
1fb30 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
1fb40 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1fb50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
1fb60 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f  aving index N, o
1fb70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55  r.**          NU
1fb80 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
1fb90 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  o SQL parameter 
1fba0 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20  with index N or 
1fbb0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
1fbc0 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
1fbd0 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20  h index N is an 
1fbe0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
1fbf0 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73  ter "?"..*/.cons
1fc00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1fc10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1fc20 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fc30 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
1fc40 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
1fc50 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
1fc60 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
1fc70 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13640}.**.** 
1fc80 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1fc90 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1fca0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1fcb0 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64  ame.  The.** ind
1fcc0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
1fcd0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
1fce0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
1fcf0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
1fd00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
1fd10 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1fd20 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a  ind()].  A zero.
1fd30 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1fd40 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
1fd50 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
1fd60 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72  .  The parameter
1fd70 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
1fd80 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
1fd90 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
1fda0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
1fdb0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
1fdc0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
1fdd0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1fde0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1fdf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1fe00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1fe10 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1fe20 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1fe30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1fe40 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
1fe50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1fe60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1fe70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1fe80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34  TS:.**.** {F1364
1fe90 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1fea0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1feb0 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ndex(S,N)] inter
1fec0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
1fed0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64           the ind
1fee0 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
1fef0 74 65 72 20 69 6e 20 5b 70 72 65 70 61 72 65 64  ter in [prepared
1ff00 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
1ff10 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20          S whose 
1ff20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65  name matches the
1ff30 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c   UTF-8 string N,
1ff40 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69   or 0 if there i
1ff50 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  s.**          no
1ff60 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73   match..*/.int s
1ff70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff80 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
1ff90 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
1ffa0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
1ffb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ffc0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
1ffd0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
1ffe0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36   Statement {F136
1fff0 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  60}.**.** Contra
20000 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
20010 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
20020 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
20030 6f 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74  oes not.** reset
20040 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
20050 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
20060 67 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72  gs] on a .** [pr
20070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20080 5d 2e 20 20 55 73 65 20 74 68 69 73 20 72 6f 75  ].  Use this rou
20090 74 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74  tine to.** reset
200a0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
200b0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
200c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
200d0 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54  **.** {F13661} T
200e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
200f0 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
20100 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
20110 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
20120 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 62 69  SQL parameter bi
20130 6e 64 69 6e 67 73 20 69 6e 20 5b 70 72 65 70 61  ndings in [prepa
20140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
20150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
20160 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  k to NULL..*/.in
20170 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
20180 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
20190 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
201a0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
201b0 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
201c0 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33   Result Set {F13
201d0 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  710}.**.** Retur
201e0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
201f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
20200 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
20210 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70  ed by the .** [p
20220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20230 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
20240 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66   returns 0.** if
20250 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
20260 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
20270 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
20280 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78  data (for .** ex
20290 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29  ample an UPDATE)
202a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
202b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31  TS:.**.** {F1371
202c0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
202d0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
202e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
202f0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
20300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
20310 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
20320 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64  lt set generated
20330 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
20340 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
20350 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
20360 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67   if S does not g
20370 65 6e 65 72 61 74 65 0a 2a 2a 20 20 20 20 20 20  enerate.**      
20380 20 20 20 20 61 20 72 65 73 75 6c 74 20 73 65 74      a result set
20390 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
203a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
203b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
203c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
203d0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
203e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
203f0 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a  t {F13720}.**.**
20400 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20410 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
20420 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
20430 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
20440 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
20450 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
20460 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
20470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20480 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
20490 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
204a0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
204b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20  terminated UTF8 
204c0 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
204d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
204e0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
204f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
20500 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
20510 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
20520 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20530 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72  er is the.** [pr
20540 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20550 5d 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  ] that implement
20560 73 20 74 68 65 20 53 45 4c 45 43 54 20 73 74 61  s the SELECT sta
20570 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  tement..** The s
20580 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20590 69 73 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75  is the column nu
205a0 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d  mber.  The left-
205b0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a  most column is.*
205c0 2a 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  * number 0..**.*
205d0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
205e0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
205f0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
20600 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  her the .** [pre
20610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20620 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
20630 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20640 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69  ze()].** or unti
20650 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
20660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20670 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
20680 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
20690 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
206a0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  column..**.** If
206b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
206c0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
206d0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
206e0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
206f0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
20700 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
20710 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
20720 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
20730 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
20740 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
20750 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
20760 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
20770 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
20780 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
20790 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
207a0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
207b0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
207c0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
207d0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
207e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
207f0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
20800 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
20810 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
20820 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
20830 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
20840 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
20850 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d  :.**.** {F13721}
20860 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
20870 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
20880 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20890 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  name(S,N)].**   
208a0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
208b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
208c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
208d0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
208e0 28 77 68 65 72 65 20 30 20 69 73 20 74 68 65 20  (where 0 is the 
208f0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
20900 29 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ) for the.**    
20910 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
20920 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
20930 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a  atement] S as a.
20940 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
20950 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
20960 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
20970 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63 65  {F13723} A succe
20980 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
20990 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
209a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
209b0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
209c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
209d0 6e 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20  ns the name.**  
209e0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e          of the N
209f0 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
20a00 20 30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d   0 is the left-m
20a10 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
20a20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20a30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
20a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20a50 74 5d 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20  t] S as a.**    
20a60 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
20a70 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72  nated UTF-16 str
20a80 69 6e 67 20 69 6e 20 74 68 65 20 6e 61 74 69 76  ing in the nativ
20a90 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
20aa0 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65  .** {F13724} The
20ab0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20ac0 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71  _name()] and [sq
20ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20ae0 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  e16()].**       
20af0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
20b00 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
20b10 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20  ter if they are 
20b20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20  unable to.**    
20b30 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d        allocate m
20b40 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
20b50 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72  eir normal retur
20b60 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a  n strings..**.**
20b70 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 65   {F13725} If the
20b80 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
20b90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
20ba0 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  name(S,N)] or.**
20bb0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20bc0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
20bd0 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66  (S,N)] is out of
20be0 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65   range, then the
20bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
20c00 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
20c10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
20c20 2a 20 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54  * .** {F13726} T
20c30 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
20c40 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20c50 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
20c60 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
20c70 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
20c80 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
20c90 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
20ca0 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
20cb0 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
20cc0 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
20cd0 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
20ce0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
20cf0 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
20d00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20d10 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
20d20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d  ..**.** {F13727}
20d30 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
20d40 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
20d50 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
20d60 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
20d70 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
20d80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
20d90 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
20da0 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20  identifier.**   
20db0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69         to the ri
20dc0 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65  ght of the AS ke
20dd0 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  yword..*/.const 
20de0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
20df0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
20e00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
20e10 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20e30 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20e40 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
20e50 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
20e60 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
20e70 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33  uery Result {F13
20e80 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  740}.**.** These
20e90 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
20ea0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
20eb0 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75  ermine what colu
20ec0 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61  mn of what.** ta
20ed0 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74  ble in which dat
20ee0 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f  abase a result o
20ef0 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  f a SELECT state
20f00 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
20f10 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
20f20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
20f30 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
20f40 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
20f50 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
20f60 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74 72  TF8 or UTF16 str
20f70 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
20f80 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
20f90 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
20fa0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
20fb0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
20fc0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
20fd0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
20fe0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
20ff0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
21000 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
21010 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21020 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
21030 0a 2a 2a 20 74 68 65 20 5b 70 72 65 70 61 72 65  .** the [prepare
21040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
21050 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
21060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
21070 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
21080 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
21090 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
210a0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
210b0 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
210c0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
210d0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
210e0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
210f0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
21100 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
21110 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
21120 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
21130 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
21140 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
21150 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65   calls is a [pre
21160 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21170 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  ..** These funct
21180 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
21190 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
211a0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
211b0 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65  urned by .** the
211c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
211d0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
211e0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
211f0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ent..**.** If th
21200 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
21210 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
21220 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
21230 72 65 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75  ression.** or su
21240 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
21250 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
21260 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
21270 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ese functions.**
21280 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 54   return NULL.  T
21290 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
212a0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
212b0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a  ULL if a memory.
212c0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ** allocation er
212d0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 4f 74 68  ror occurs.  Oth
212e0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
212f0 75 72 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65  urn the .** name
21300 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
21310 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
21320 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74   and column that
21330 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
21340 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
21350 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
21360 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74  * As with all ot
21370 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
21380 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64   those postfixed
21390 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
213a0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
213b0 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65  ded strings, the
213c0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
213d0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b   return UTF-8. {
213e0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
213f0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
21400 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
21410 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
21420 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  iled with the .*
21430 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  * SQLITE_ENABLE_
21440 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20  COLUMN_METADATA 
21450 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
21460 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
21470 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49  ** {U13751}.** I
21480 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
21490 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
214a0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
214b0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
214c0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
214d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
214e0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
214f0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
21500 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
21510 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
21520 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21530 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20  .**.** {F13741} 
21540 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
21550 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
21560 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
21570 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
21580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
21590 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
215a0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
215b0 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
215c0 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
215d0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
215e0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
215f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21600 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
21610 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
21620 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
21630 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
21640 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
21650 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
21660 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
21670 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
21680 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
21690 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
216a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
216b0 20 7b 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {F13742} The [s
216c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
216d0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
216e0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
216f0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
21700 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
21710 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
21720 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
21730 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
21740 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
21750 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
21760 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
21770 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
21780 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
21790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
217a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
217b0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
217c0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
217d0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a  umn of S is a.**
217e0 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61            genera
217f0 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
21800 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
21810 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
21820 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
21830 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20  e the name..**  
21840 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33          .** {F13
21850 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  743} The [sqlite
21860 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
21870 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
21880 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
21890 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
218a0 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
218b0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
218c0 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20   the table from 
218d0 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20  which the .**   
218e0 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
218f0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65  t column of [pre
21900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21910 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S .**          
21920 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
21930 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
21940 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
21950 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65  a.**          ge
21960 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
21970 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
21980 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
21990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
219a0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
219b0 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20  **          .** 
219c0 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {F13744} The [sq
219d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
219e0 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
219f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
21a00 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
21a10 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
21a20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
21a30 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
21a40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
21a50 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
21a60 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
21a70 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
21a80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
21a90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21aa0 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
21ab0 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
21ac0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
21ad0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
21ae0 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
21af0 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
21b00 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
21b10 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
21b20 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
21b30 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
21b40 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
21b50 20 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54 68   .** {F13745} Th
21b60 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
21b70 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
21b80 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
21b90 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
21ba0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
21bb0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
21bc0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
21bd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
21be0 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
21bf0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
21c00 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
21c10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21c20 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
21c30 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
21c40 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
21c50 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
21c60 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
21c70 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
21c80 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
21c90 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
21ca0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
21cb0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
21cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
21cd0 20 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73   {F13746} The [s
21ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
21cf0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  igin_name16(S,N)
21d00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
21d10 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
21d20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
21d30 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
21d40 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
21d50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
21d60 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
21d70 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68  e column from wh
21d80 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
21d90 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
21da0 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
21db0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
21dc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
21dd0 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
21de0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
21df0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
21e00 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
21e10 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
21e20 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
21e30 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
21e40 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
21e50 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
21e60 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
21e70 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72  13748} The retur
21e80 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a  n values from.**
21e90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
21eb0 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d  se_name|column m
21ec0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
21ed0 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
21ee0 61 72 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20  are valid.**    
21ef0 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 6c 69        for the li
21f00 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70  fetime of the [p
21f10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21f20 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  t].**          o
21f30 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f  r until the enco
21f40 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20  ding is changed 
21f50 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64  by another metad
21f60 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
21f70 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66  interface call f
21f80 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70  or the same prep
21f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
21fa0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
21fb0 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
21fc0 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49 66 20  .** {U13751} If 
21fd0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
21fe0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
21ff0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
22000 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22010 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63  _database_name|c
22020 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
22030 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
22040 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
22050 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22060 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
22070 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
22080 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74     at the same t
22090 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
220a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
220b0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
220c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
220d0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
220e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
220f0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
22100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22110 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
22120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
22130 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
22140 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
22150 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
22160 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
22170 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
22180 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
22190 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
221a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
221b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
221c0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
221d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
221e0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
221f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
22200 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
22210 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22230 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
22240 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
22250 65 73 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a  esult {F13760}.*
22260 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
22270 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
22280 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22290 74 5d 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20  t]. .** If this 
222a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53  statement is a S
222b0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20  ELECT statement 
222c0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
222d0 6d 6e 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65  mn of the .** re
222e0 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
222f0 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54  t of that SELECT
22300 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
22310 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
22320 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
22330 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
22340 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
22350 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
22360 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
22370 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
22380 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
22390 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
223a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
223b0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
223c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
223d0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
223e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
223f0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
22400 6e 63 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a  ncoded.  {END} .
22410 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
22420 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
22430 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
22440 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
22450 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
22460 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   And the followi
22470 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  ng statement com
22480 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
22490 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
224a0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68  ROM t1;.**.** Th
224b0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
224c0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
224d0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
224e0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
224f0 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  .** result colum
22500 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
22510 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
22520 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
22530 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d  t column.** (i==
22540 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
22550 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
22560 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
22570 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
22580 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
22590 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
225a0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
225b0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
225c0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
225d0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
225e0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
225f0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
22600 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
22610 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
22620 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
22630 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
22640 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
22650 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
22660 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
22670 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
22680 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
22690 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
226a0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
226b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
226c0 0a 2a 2a 20 7b 46 31 33 37 36 31 7d 20 20 41 20  .** {F13761}  A 
226d0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
226e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
226f0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
22700 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ].**           r
22710 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65  eturns a zero-te
22720 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
22730 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
22740 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
22750 20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64    the declared d
22760 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
22770 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
22780 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
22790 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
227a0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
227b0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
227c0 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
227d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
227e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
227f0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
22800 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
22810 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
22820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
22830 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
22840 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
22850 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
22860 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
22870 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
22880 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
22890 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
228a0 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
228b0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
228c0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
228d0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
228e0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
228f0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
22900 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
22910 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
22920 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
22930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22940 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33  S..**.** {F13763
22950 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
22960 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
22970 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
22980 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
22990 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
229a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70  of columns in [p
229b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
229c0 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  t] S.**         
229d0 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20    or if the Nth 
229e0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
229f0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  n expression or 
22a00 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a  subquery rather.
22a10 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
22a20 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  n a table column
22a30 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
22a40 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
22a50 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
22a60 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
22a70 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
22a80 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
22a90 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
22aa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22ab0 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
22ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
22ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
22ae0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
22af0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
22b00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22b10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
22b20 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
22b30 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
22b40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
22b50 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
22b60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22b70 0a 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45  ../* .** CAPI3RE
22b80 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20  F:  Evaluate An 
22b90 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
22ba0 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74  13200}.**.** Aft
22bb0 65 72 20 61 6e 20 5b 70 72 65 70 61 72 65 64 20  er an [prepared 
22bc0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
22bd0 65 65 6e 20 70 72 65 70 61 72 65 64 20 77 69 74  een prepared wit
22be0 68 20 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65  h a call.** to e
22bf0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
22c00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
22c10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22c20 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f  16_v2()] or to o
22c30 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67  ne of.** the leg
22c40 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
22c50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22c60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
22c70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20  repare16()],.** 
22c80 74 68 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69  then this functi
22c90 6f 6e 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  on must be calle
22ca0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
22cb0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
22cc0 74 68 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  the .** statemen
22cd0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
22ce0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
22cf0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c  vior of this sql
22d00 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
22d10 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
22d20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
22d30 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
22d40 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
22d50 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
22d60 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
22d70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
22d80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
22d90 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
22da0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
22db0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
22dc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
22dd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
22de0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
22df0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
22e00 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
22e10 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
22e20 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
22e30 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
22e40 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
22e50 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
22e60 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
22e70 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
22e80 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
22e90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
22ea0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
22eb0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a  [SQLITE_BUSY], .
22ec0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
22ed0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
22ee0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
22ef0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
22f00 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  E]..** With the 
22f10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
22f20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
22f30 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
22f40 73 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72  sult code].** or
22f50 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52   [SQLITE_IOERR_R
22f60 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72  EAD | extended r
22f70 65 73 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68  esult code] migh
22f80 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
22f90 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  .** well..**.** 
22fa0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
22fb0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
22fc0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
22fd0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
22fe0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
22ff0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
23000 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
23010 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
23020 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a  nt is a COMMIT.*
23030 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
23040 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
23050 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
23060 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
23070 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
23080 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
23090 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
230a0 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72  COMMIT and occur
230b0 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
230c0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
230d0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
230e0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
230f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
23100 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
23110 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
23120 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
23130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
23140 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
23150 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
23160 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
23170 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
23180 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
23190 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
231a0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
231b0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
231c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
231d0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
231e0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
231f0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
23200 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
23210 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
23220 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
23230 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
23240 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
23250 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57   .** [SQLITE_ROW
23260 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  ] is returned ea
23270 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
23280 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
23290 64 79 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73  dy.** for proces
232a0 73 69 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c  sing by the call
232b0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
232c0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
232d0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
232e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
232f0 7c 20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20  | column access 
23300 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
23310 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
23320 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
23330 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
23340 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
23350 2a 2a 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ** .** [SQLITE_E
23360 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
23370 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
23380 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
23390 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
233a0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
233b0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
233c0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
233d0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
233e0 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
233f0 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
23400 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
23410 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
23420 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
23430 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
23440 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
23450 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
23460 64 65 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20  de (example:.** 
23470 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
23480 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
23490 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
234a0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
234b0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
234c0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
234d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
234e0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
234f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23500 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32  nt].  In the "v2
23510 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
23520 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
23530 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
23540 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
23550 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
23560 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
23570 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
23580 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
23590 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
235a0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
235b0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
235c0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
235d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
235e0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
235f0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
23600 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23610 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
23620 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
23630 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20   .** previously 
23640 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
23650 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
23660 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
23670 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
23680 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
23690 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
236a0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
236b0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
236c0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
236d0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
236e0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
236f0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
23700 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a  face Alert:</b>.
23710 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
23720 20 69 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20   interface, .** 
23730 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
23740 28 29 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  () API always re
23750 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
23760 65 72 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b  error code,.** [
23770 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
23780 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72  ollowing any err
23790 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
237a0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61  QLITE_BUSY].** a
237b0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
237c0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
237d0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ll [sqlite3_rese
237e0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
237f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23800 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
23810 20 6f 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63   one of the spec
23820 69 66 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  ific.** [error c
23830 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
23840 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
23850 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
23860 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
23870 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
23880 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
23890 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
238a0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
238b0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
238c0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
238d0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
238e0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
238f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
23900 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
23910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23920 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
23930 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
23940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
23950 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23960 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
23970 65 6e 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20  en the .** more 
23980 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
23990 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
239a0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
239b0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
239c0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
239d0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
239e0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
239f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
23a00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30  TS:.**.** {F1320
23a10 32 7d 20 20 49 66 20 5b 70 72 65 70 61 72 65 64  2}  If [prepared
23a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
23a30 20 72 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20   ready to be.** 
23a40 20 20 20 20 20 20 20 20 20 20 72 75 6e 2c 20 74            run, t
23a50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  hen [sqlite3_ste
23a60 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74  p(S)] advances t
23a70 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61  hat prepared sta
23a80 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  tement.**       
23a90 20 20 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d      until to com
23aa0 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c  pletion or until
23ab0 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20   it is ready to 
23ac0 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a  return another.*
23ad0 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  *           row 
23ae0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
23af0 74 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70  t or an interrup
23b00 74 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72  t or run-time er
23b10 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
23b20 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65 6e  * {F15304}  When
23b30 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
23b40 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75  te3_step(S)] cau
23b50 73 65 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ses the .**     
23b60 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
23b70 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
23b80 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
23b90 6e 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  n,.**           
23ba0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
23bb0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  urns [SQLITE_DON
23bc0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30  E]..**.** {F1530
23bd0 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  6}  When a call 
23be0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
23bf0 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75  (S)] stops becau
23c00 73 65 20 69 74 20 69 73 20 72 65 61 64 79 0a 2a  se it is ready.*
23c10 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 72  *           to r
23c20 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
23c30 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
23c40 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 0a  set, it returns.
23c50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51  **           [SQ
23c60 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ROW]..**.**
23c70 20 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61 20   {F15308}  If a 
23c80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
23c90 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e  _step(S)] encoun
23ca0 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ters an.**      
23cb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e       [sqlite3_in
23cc0 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75 70  terrupt|interrup
23cd0 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65  t] or a run-time
23ce0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
23cf0 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20       it returns 
23d00 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
23d10 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69  rror code that i
23d20 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20  s not one of.** 
23d30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
23d40 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  E_OK], [SQLITE_R
23d50 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OW], or [SQLITE_
23d60 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  DONE]..**.** {F1
23d70 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71  5310}  If an [sq
23d80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 7c  lite3_interrupt|
23d90 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 72 75  interrupt] or ru
23da0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20  n-time error.** 
23db0 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73            occurs
23dc0 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74   during a call t
23dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
23de0 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
23df0 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64   for a [prepared
23e00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72   statement] S cr
23e10 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
23e20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20           legacy 
23e30 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
23e40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
23e50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
23e60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23e70 36 28 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75  6()] then the fu
23e80 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65  nction returns e
23e90 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
23ea0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
23eb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
23ec0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
23ed0 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  USE]..*/.int sql
23ee0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
23ef0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
23f00 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
23f10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
23f20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 46 31  a result set {F1
23f30 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3770}.**.** Retu
23f40 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
23f50 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63   values in the c
23f60 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
23f70 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a  e result set..**
23f80 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
23f90 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20  **.** {F13771}  
23fa0 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20  After a call to 
23fb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
23fc0 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 0a 2a  ] that returns.*
23fd0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
23fe0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73  ITE_ROW], the [s
23ff0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
24000 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a  t(S)] routine.**
24010 20 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20             will 
24020 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
24030 76 61 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a 20  value as the.** 
24040 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24050 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
24060 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  S)] function..**
24070 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41 66  .** {F13772}  Af
24080 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
24090 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e  p(S)] has return
240a0 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ed any value oth
240b0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
240c0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
240d0 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c  ] or before [sql
240e0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
240f0 73 20 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20  s been .**      
24100 20 20 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74       called on t
24110 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24120 74 65 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20  tement] for.**  
24130 20 20 20 20 20 20 20 20 20 74 68 65 20 66 69 72           the fir
24140 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74  st time since it
24150 20 77 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72   was [sqlite3_pr
24160 65 70 61 72 65 7c 70 72 65 70 61 72 65 64 5d 0a  epare|prepared].
24170 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
24180 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 7c 72  [sqlite3_reset|r
24190 65 73 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69  eset], the [sqli
241a0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
241b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
241c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
241d0 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
241e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
241f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24200 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24210 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
24220 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46 31  al Datatypes {F1
24230 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0265}.** KEYWORD
24240 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
24250 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76 65  *.** {F10266}Eve
24260 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
24270 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
24280 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
24290 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
242a0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
242b0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
242c0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
242d0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
242e0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
242f0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
24300 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
24310 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b   NULL.** </ul> {
24320 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  END}.**.** These
24330 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
24340 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
24350 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
24360 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
24370 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
24380 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
24390 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
243a0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
243b0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
243c0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
243d0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
243e0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
243f0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
24400 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
24410 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
24420 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
24430 58 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  XT not.** SQLITE
24440 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
24450 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
24460 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
24470 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
24480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
24490 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
244a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
244b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
244c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
244d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
244e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
244f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
24500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
24510 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
24520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
24530 75 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d  ults Values From
24540 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30 30   A Query {F13800
24550 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
24560 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
24570 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72  "result set quer
24580 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  y" interface..**
24590 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
245a0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
245b0 61 74 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61  ation about.** a
245c0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
245d0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  f the current re
245e0 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
245f0 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a  ery.  In every.*
24600 2a 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  * case the first
24610 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24620 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ointer to the .*
24630 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24640 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
24650 65 69 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65  eing.** evaluate
24660 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
24670 73 74 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20  stmt*] that was 
24680 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a  returned from .*
24690 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
246a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
246b0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
246c0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f   and.** the seco
246d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
246e0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
246f0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
24700 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a   information .**
24710 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
24720 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d  ned.  The left-m
24730 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
24740 65 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  e result set.** 
24750 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
24760 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
24770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
24780 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
24790 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
247a0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
247b0 2a 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64  * the column ind
247c0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
247d0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
247e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a  s undefined. .**
247f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24800 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
24810 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
24820 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
24830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
24840 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
24850 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
24860 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
24870 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
24880 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
24890 6c 69 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e  lize()] has been
248a0 20 63 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74   call subsequent
248b0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
248c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
248d0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
248e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
248f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
24900 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
24910 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
24920 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
24930 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
24940 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
24950 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
24960 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
24970 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
24980 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
24990 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
249a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
249b0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
249c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
249d0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
249e0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
249f0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
24a00 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
24a10 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
24a20 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a   undefined.  .**
24a30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
24a40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
24a50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a  utine returns .*
24a60 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
24a70 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
24a80 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
24a90 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
24aa0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
24ab0 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
24ac0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
24ad0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
24ae0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
24af0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
24b00 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
24b10 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
24b20 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
24b30 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
24b40 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24b50 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
24b60 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
24b70 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
24b80 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
24b90 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
24ba0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
24bb0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24bc0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
24bd0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
24be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
24bf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
24c00 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
24c10 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
24c20 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
24c30 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
24c40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
24c50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
24c60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
24c70 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
24c80 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
24c90 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
24ca0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
24cb0 75 6d 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20  umn_bytes() .** 
24cc0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
24cd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
24ce0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
24cf0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
24d00 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
24d10 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
24d20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
24d30 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
24d40 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
24d50 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
24d60 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
24d70 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
24d80 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
24d90 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
24da0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
24db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24dc0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
24dd0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
24de0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
24df0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
24e00 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
24e10 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
24e20 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
24e30 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
24e40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
24e50 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
24e60 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
24e70 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
24e80 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
24e90 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
24ea0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
24eb0 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
24ec0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
24ed0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
24ee0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
24ef0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
24f00 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
24f10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
24f20 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
24f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24f40 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
24f50 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
24f60 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
24f70 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
24f80 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
24f90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
24fa0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
24fb0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f   zero-length blo
24fc0 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  b is an arbitrar
24fd0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
24fe0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
24ff0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
25000 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
25010 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
25020 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
25030 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
25040 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
25050 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
25060 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
25070 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
25080 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
25090 54 46 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a  TF-8.  .** The z
250a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
250b0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
250c0 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
250d0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
250e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
250f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25100 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
25110 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25120 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
25130 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
25140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25150 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
25160 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
25170 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
25180 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
25190 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
251a0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
251b0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
251c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
251d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
251e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
251f0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
25200 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
25210 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
25220 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
25230 73 20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69  s like .** [sqli
25240 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
25250 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
25260 5f 74 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71  _text()], or [sq
25270 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
25280 73 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  s()],.** then th
25290 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
252a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
252b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
252c0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
252d0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
252e0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
252f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
25300 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
25310 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
25320 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
25330 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
25340 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
25350 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
25360 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
25370 79 20 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76  y to do the conv
25380 65 72 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61  ersion.** automa
25390 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f  tically.  The fo
253a0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
253b0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
253c0 73 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72  sions that.** ar
253d0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
253e0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
253f0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
25400 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
25410 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
25420 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
25430 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
25440 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
25450 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
25460 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
25470 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
25480 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
25490 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
254a0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
254b0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
254c0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
254d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
254e0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
254f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
25500 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
25510 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
25520 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
25530 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
25540 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
25550 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
25560 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
25570 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
25580 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
25590 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
255a0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
255b0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
255c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
255d0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
255e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
255f0 53 61 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45  Same as for INTE
25600 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
25610 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
25620 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
25630 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
25640 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
25650 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
25660 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
25670 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
25680 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
25690 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
256a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
256b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
256c0 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
256d0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
256e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
256f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
25700 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
25710 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
25720 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
25730 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
25740 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
25750 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
25760 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
25770 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
25780 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
25790 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
257a0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
257b0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
257c0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
257d0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
257e0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
257f0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
25800 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
25810 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
25820 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
25830 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
25840 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
25850 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
25860 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
25870 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
25880 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
25890 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
258a0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
258b0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
258c0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
258d0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
258e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
258f0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
25900 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
25910 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
25920 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
25930 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
25940 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
25950 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
25960 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
25970 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
25980 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
25990 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
259a0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
259b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
259c0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
259d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
259e0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
259f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25a00 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
25a10 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
25a20 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
25a30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
25a40 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
25a50 64 2e 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  d. .** Type conv
25a60 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
25a70 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
25a80 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
25a90 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
25aa0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
25ab0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  ul>.** <li><p>  
25ac0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
25ad0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
25ae0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25af0 5f 74 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20  _text() .**     
25b00 20 20 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f       or sqlite3_
25b10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
25b20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
25b30 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
25b40 67 68 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ght.**          
25b50 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
25b60 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
25b70 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  /p></li>.**.** <
25b80 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74  li><p>  The init
25b90 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
25ba0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
25bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25bc0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
25bd0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
25be0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
25bf0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
25c00 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
25c10 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
25c20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
25c30 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  p></li>.**.** <l
25c40 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69  i><p>  The initi
25c50 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
25c60 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
25c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25c80 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
25c90 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
25ca0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
25cb0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
25cc0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
25cd0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
25ce0 74 6f 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c  to UTF-8.</p></l
25cf0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
25d00 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65  * Conversions be
25d10 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
25d20 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
25d30 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
25d40 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
25d50 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
25d60 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
25d70 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
25d80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
25d90 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
25da0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
25db0 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
25dc0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
25dd0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
25de0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
25df0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
25e00 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
25e10 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
25e20 73 6f 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a  sometime it is.*
25e30 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  * not possible a
25e40 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
25e50 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
25e60 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
25e70 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  .  .**.** The sa
25e80 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
25e90 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
25ea0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
25eb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
25ec0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
25ed0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
25ee0 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20  .**.**  <ul>.** 
25ef0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
25f00 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
25f10 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
25f20 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
25f30 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
25f40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
25f50 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
25f60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25f70 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
25f80 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
25f90 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
25fa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25fb0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
25fc0 69 3e 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a  i>.**  </ul>.**.
25fd0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
25fe0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
25ff0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
26000 6e 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  n_text(), sqlite
26010 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
26020 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
26030 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
26040 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
26050 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68  e result into th
26060 65 20 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72  e desired.** for
26070 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
26080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26090 62 79 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74  bytes() or sqlit
260a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
260b0 36 28 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74  6() to.** find t
260c0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
260d0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
260e0 69 78 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ix call to sqlit
260f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
26100 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
26110 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
26120 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
26130 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26140 36 28 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74  6().  And do not
26150 0a 2a 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  .** mix calls to
26160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26170 74 65 78 74 31 36 28 29 20 77 69 74 68 20 63 61  text16() with ca
26180 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
26190 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
261a0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
261b0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
261c0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
261d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
261e0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
261f0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
26200 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
26210 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
26220 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
26230 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26240 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
26250 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63   The memory spac
26260 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
26270 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c  trings.** and bl
26280 6f 62 73 20 69 73 20 66 72 65 65 64 20 61 75 74  obs is freed aut
26290 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
262a0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
262b0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
262c0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
262d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
262e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
262f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
26300 69 6e 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  into .** [sqlite
26310 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
26320 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
26330 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
26340 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
26350 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
26360 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
26370 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
26380 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
26390 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
263a0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
263b0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
263c0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
263d0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
263e0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
263f0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
26400 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
26410 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
26420 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
26430 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
26440 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
26450 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33  S:.**.** {F13803
26460 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
26470 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
26480 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
26490 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
264a0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
264b0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
264c0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
264d0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
264e0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
264f0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
26500 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20  a blob and then 
26510 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
26520 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
26530 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76   the converted v
26540 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  alue..**.** {F13
26550 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  806} The [sqlite
26560 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53  3_column_bytes(S
26570 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
26580 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
26590 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
265a0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c   bytes in the bl
265b0 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  ob or string (ex
265c0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
265d0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
265e0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
265f0 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
26600 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
26610 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
26620 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
26630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
26640 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72  mn_blob(S,N)] or
26650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
26660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26670 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  t(S,N)]..**.** {
26680 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c  F13809} The [sql
26690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
266a0 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  s16(S,N)] interf
266b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
266c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
266d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
266e0 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
266f0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
26700 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
26710 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
26720 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
26730 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
26740 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
26750 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
26760 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26770 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a  text16(S,N)]..**
26780 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65  .** {F13812} The
26790 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
267a0 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e  _double(S,N)] in
267b0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
267c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
267d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
267e0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
267f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
26800 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
26810 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26820 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
26830 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
26840 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
26850 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
26860 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
26870 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d  ..**.** {F13815}
26880 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
26890 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
268a0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
268b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
268c0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
268d0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
268e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
268f0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
26900 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
26910 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
26920 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
26930 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
26940 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
26950 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
26960 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
26970 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20  .**.** {F13818} 
26980 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
26990 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
269a0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
269b0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
269c0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
269d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
269e0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
269f0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
26a00 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
26a10 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
26a20 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
26a30 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
26a40 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
26a50 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
26a60 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
26a70 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3821} The [sqlit
26a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
26a90 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
26aa0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
26ab0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
26ac0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
26ad0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
26ae0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
26af0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
26b00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
26b10 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
26b20 6e 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20  nated UTF-8 .** 
26b30 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
26b40 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
26b50 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
26b60 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
26b70 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
26b80 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
26b90 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
26ba0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
26bb0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
26bc0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
26bd0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
26be0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
26bf0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
26c00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26c10 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
26c20 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
26c30 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
26c40 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
26c50 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
26c60 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
26c70 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
26c80 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
26c90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  ng..**.** {F1382
26ca0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
26cb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
26cc0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
26cd0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
26ce0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
26cf0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
26d00 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
26d10 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
26d20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
26d30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
26d40 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
26d50 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
26d60 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
26d70 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
26d80 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
26d90 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
26da0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
26db0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
26dc0 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68  *.** {F13830} Th
26dd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
26de0 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e  n_value(S,N)] in
26df0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26e00 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
26e10 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70  inter to an [unp
26e20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26e30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
26e40 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
26e50 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
26e60 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
26e70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
26e80 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
26e90 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
26ea0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f  tement] S..*/.co
26eb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
26ec0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
26ed0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26ee0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
26ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26f10 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
26f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26f30 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
26f40 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
26f50 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
26f60 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
26f70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26f80 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
26f90 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
26fa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26fb0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
26fc0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
26fd0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
26fe0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26ff0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
27000 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
27010 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
27020 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27030 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
27040 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
27050 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
27060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27070 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
27080 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
27090 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
270a0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
270b0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
270c0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
270d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
270e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
270f0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
27100 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27110 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30  t Object {F13300
27120 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
27130 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
27140 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
27150 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a  d to delete a .*
27160 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
27170 65 6d 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73  ement]. If the s
27180 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
27190 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
271a0 66 75 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78  fully, or not ex
271b0 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
271c0 68 65 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  hen SQLITE_OK is
271d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
271e0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
271f0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
27200 65 64 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b  ed then an .** [
27210 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
27220 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
27230 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
27240 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ned. .**.** This
27250 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
27260 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
27270 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
27280 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
27290 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
272a0 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
272b0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
272c0 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d   has not .** com
272d0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
272e0 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
272f0 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
27300 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
27310 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
27320 72 6f 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72  ror or an interr
27330 75 70 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69  upt.  (See [sqli
27340 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
27350 2e 29 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  .) .** Incomplet
27360 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
27370 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
27380 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
27390 6e 63 65 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70  nceled,  .** dep
273a0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
273b0 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
273c0 20 74 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20   the .** [error 
273d0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
273e0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
273f0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  BORT]..**.** INV
27400 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
27410 46 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c  F11302} The [sql
27420 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
27430 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
27440 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  roys the.**     
27450 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
27460 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20  tatement] S and 
27470 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20  releases all.** 
27480 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
27490 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63  and file resourc
274a0 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20  es held by that 
274b0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  object..**.** {F
274c0 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f  11304} If the mo
274d0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
274e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
274f0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
27500 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
27510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
27520 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72  eturned an error
27530 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
27540 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
27550 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73  lize(S)] returns
27560 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72   that same error
27570 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27580 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
27590 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
275a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
275b0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
275c0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
275d0 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a  ct {F13330}.**.*
275e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
275f0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
27600 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
27610 74 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65  t a .** [prepare
27620 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
27630 65 63 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  ect..** back to 
27640 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
27650 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
27660 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41  e-executed..** A
27670 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
27680 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
27690 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
276a0 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
276b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
276c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
276d0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
276e0 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
276f0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
27700 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
27710 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
27720 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
27730 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68  *.** {F11332} Th
27740 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
27750 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
27760 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
27770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63  .**          bac
27790 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
277a0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
277b0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34  m..**.** {F11334
277c0 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
277d0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
277e0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
277f0 6f 72 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or .**          
27800 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27810 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
27820 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
27830 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
27840 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
27850 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27860 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
27870 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
27880 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
27890 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
278a0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
278b0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
278c0 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66  *.** {F11336} If
278d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
278e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
278f0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a  3_step(S)] for.*
27900 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
27910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27920 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
27930 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
27940 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27950 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
27960 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
27970 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
27980 2a 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68  *.** {F11338} Th
27990 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
279a0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
279b0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
279c0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
279d0 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
279e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
279f0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72  bindings] on [pr
27a00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a10 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
27a20 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
27a30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27a40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a50 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
27a60 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
27a70 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45  s {F16100}.** KE
27a80 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
27a90 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
27aa0 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73  nes} .**.** Thes
27ab0 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
27ac0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
27ad0 6f 77 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74  own as.** "funct
27ae0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
27af0 74 69 6e 65 73 22 29 20 61 72 65 20 75 73 65 64  tines") are used
27b00 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
27b10 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
27b20 74 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64  tes.** or to red
27b30 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
27b40 6f 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  or of existing S
27b50 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
27b60 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
27b70 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f  .** difference o
27b80 6e 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20  nly between the 
27b90 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
27ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
27bb0 2c 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66  , the.** name of
27bc0 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
27bd0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
27be0 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
27bf0 69 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  in UTF-8 for.** 
27c00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27c10 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
27c20 46 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33  F-16 for sqlite3
27c30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27c40 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
27c50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
27c60 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
27c70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
27c80 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
27c90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
27ca0 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
27cb0 73 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61  single.** progra
27cc0 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
27cd0 20 6f 6e 65 20 5b 64 61 74 61 62 61 73 65 20 63   one [database c
27ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72  onnection] inter
27cf0 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a  nally, then SQL.
27d00 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  ** functions mus
27d10 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
27d20 69 64 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20  idually to each 
27d30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27d40 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tion]..**.** The
27d50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
27d60 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
27d70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27d80 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a  n to be created.
27d90 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e  ** or redefined.
27da0 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f  .** The length o
27db0 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
27dc0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
27dd0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
27de0 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65   the .** zero-te
27df0 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
27e00 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
27e10 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
27e20 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
27e30 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20  haracters.  Any 
27e40 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
27e50 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
27e60 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
27e70 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
27e80 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  n an SQLITE_ERRO
27e90 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  R error..**.** T
27ea0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
27eb0 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  er is the number
27ec0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
27ed0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
27ee0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
27ef0 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68  ate takes. If th
27f00 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
27f10 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
27f20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
27f30 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
27f40 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
27f50 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
27f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
27f70 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
27f80 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
27f90 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49  s what .** [SQLI
27fa0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
27fb0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
27fc0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
27fd0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
27fe0 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
27ff0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
28000 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
28010 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
28020 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
28030 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
28040 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
28050 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
28060 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
28070 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
28080 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
28090 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
280a0 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74   It is allowed t
280b0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
280c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
280d0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
280e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
280f0 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
28100 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
28110 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
28120 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
28130 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
28140 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c  Rep..** When mul
28150 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
28160 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
28170 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
28180 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
28190 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
281a0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
281b0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
281c0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
281d0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
281e0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
281f0 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
28200 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
28210 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a  not care what.**
28220 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69   text encoding i
28230 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
28240 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
28250 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53   should be.** [S
28260 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
28270 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
28280 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
28290 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
282a0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
282b0 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e  on.** of the fun
282c0 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
282d0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
282e0 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b  inter using.** [
282f0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
28300 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  a()]..**.** The 
28310 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
28320 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
28330 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
28340 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
28350 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
28360 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
28370 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
28380 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a  ement the SQL.**
28390 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
283a0 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72  regate. A scalar
283b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
283c0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
283d0 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  entation of.** t
283e0 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63  he xFunc callbac
283f0 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69  k only, NULL poi
28400 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
28410 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
28420 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
28430 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e  l parameters. An
28440 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
28450 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
28460 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
28470 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61  on.** of xStep a
28480 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
28490 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
284a0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54  sed for xFunc. T
284b0 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65  o delete an.** e
284c0 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
284d0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
284e0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
284f0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
28500 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
28510 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
28520 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
28530 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
28540 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
28550 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
28560 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
28570 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
28580 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
28590 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
285a0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
285b0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
285c0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
285d0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
285e0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
285f0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
28600 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
28610 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
28620 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
28630 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
28640 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
28650 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65  .** {F16103} The
28660 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28670 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69  _function16()] i
28680 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73  nterface behaves
28690 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
286a0 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74       like [sqlit
286b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
286c0 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77  on()] in every w
286d0 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
286e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
286f0 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75  terprets the zFu
28700 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d  nctionName argum
28710 65 6e 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20  ent as.**       
28720 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
28730 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
28740 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
28750 65 61 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20  ead of as a.**  
28760 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
28770 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a  minated UTF-8..*
28780 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20  *.** {F16106} A 
28790 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
287a0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20  ation of.**     
287b0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
287c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
287d0 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20  n(D,X,N,E,...)] 
287e0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
287f0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
28800 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c  or replaces call
28810 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69  back functions i
28820 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
28830 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
28840 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d        used to im
28850 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
28860 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58  function named X
28870 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65   with N paramete
28880 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rs.**          a
28890 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 66  nd having a pref
288a0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
288b0 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20  ing of E..**.** 
288c0 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63 63 65  {F16109} A succe
288d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
288e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
288f0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
28900 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
28910 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74 68       replaces th
28920 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c  e P, F, S, and L
28930 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79   values from any
28940 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
28950 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
28960 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20  e same D, X, N, 
28970 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a  and E values..**
28980 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65  .** {F16112} The
28990 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
289a0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e  _function(D,X,..
289b0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
289c0 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ils with.**     
289d0 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f       a return co
289e0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52  de of [SQLITE_ER
289f0 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20  ROR] if the SQL 
28a00 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20  function name X 
28a10 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  is.**          l
28a20 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62  onger than 255 b
28a30 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f  ytes exclusive o
28a40 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  f the zero termi
28a50 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
28a60 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d  6118} Either F m
28a70 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20  ust be NULL and 
28a80 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
28a90 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a  NULL or else F.*
28aa0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
28ab0 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  n-NULL and S and
28ac0 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68   L are NULL, oth
28ad0 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20  erwise.**       
28ae0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
28af0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
28b00 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65  N,E,P,F,S,L)] re
28b10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
28b20 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ROR]..**.** {F16
28b30 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
28b40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28b50 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
28b60 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
28b70 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
28b80 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
28b90 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65  ITE_BUSY] if the
28ba0 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72  re exist [prepar
28bb0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
28bc0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63  *          assoc
28bd0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
28be0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28bf0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
28c00 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16124} The [sqli
28c10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28c20 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20  ion(D,X,N,...)] 
28c30 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
28c40 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
28c50 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
28c60 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
28c70 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
28c80 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20  (specifying the 
28c90 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
28ca0 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20     of arguments 
28cb0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
28cc0 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74  ion being regist
28cd0 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a  ered) is less.**
28ce0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
28cf0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
28d00 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  n 127..**.** {F1
28d10 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
28d20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
28d30 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
28d40 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
28d50 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
28d60 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
28d70 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
28d80 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
28d90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
28da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
28db0 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75  ed X when the nu
28dc0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
28dd0 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
28de0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ction is.**     
28df0 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a       exactly N..
28e00 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57  **.** {F16130} W
28e10 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65  hen N is -1, the
28e20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28e30 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
28e40 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
28e50 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73    interface caus
28e60 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  es callbacks to 
28e70 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
28e80 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
28e90 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
28ea0 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d  d X with any num
28eb0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
28ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d  ..**.** {F16133}
28ed0 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
28ee0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28ef0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
28f00 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
28f10 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
28f20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28f30 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
28f40 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20  ction X.**      
28f50 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65      and when one
28f60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28f70 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65  has N>=0 and the
28f80 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31   other has N=(-1
28f90 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ).**          th
28fa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
28fb0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
28fc0 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64 2e   N is preferred.
28fd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20  .**.** {F16136} 
28fe0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
28ff0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29000 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
29010 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
29020 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
29030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29040 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
29050 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a  nction X with.**
29060 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
29070 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  me number of arg
29080 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74  uments N but wit
29090 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20  h different.**  
290a0 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67          encoding
290b0 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d  s E, then the im
290c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
290d0 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65  re E matches the
290e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
290f0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
29100 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  s preferred..**.
29110 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20  ** {F16139} For 
29120 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  an aggregate SQL
29130 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65   function create
29140 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
29150 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
29160 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
29170 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74  ,N,E,P,0,S,L)] t
29180 68 65 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a  he finializer.**
29190 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
291a0 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73  on L will always
291b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   be invoked exac
291c0 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a  tly once if the.
291d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70  **          step
291e0 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63   function S is c
291f0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
29200 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  e times..**.** {
29210 46 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c  F16142} When SQL
29220 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68  ite invokes eith
29230 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  er the xFunc or 
29240 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f  xStep function o
29250 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  f.**          an
29260 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29270 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29280 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63  n or aggregate c
29290 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  reated.**       
292a0 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
292b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
292c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72  ] or [sqlite3_cr
292d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
292e0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
292f0 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f  then the array o
29300 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
29310 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64  ] objects passed
29320 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   as the.**      
29330 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65      third parame
29340 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b  ter are always [
29350 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29360 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
29370 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29380 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29390 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
293a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
293b0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
293c0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
293d0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
293e0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
293f0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
29400 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
29410 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
29420 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
29430 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29440 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
29450 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
29460 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
29470 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
29480 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29490 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
294a0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
294b0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
294c0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
294d0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
294e0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
294f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
29500 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29510 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
29520 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
29530 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
29540 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
29550 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
29560 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
29570 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29580 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
29590 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
295a0 69 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a  ings {F10267}.**
295b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
295c0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
295d0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
295e0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
295f0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
29600 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
29610 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
29620 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
29630 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
29640 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
29650 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
29660 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
29670 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
29680 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
29690 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
296a0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
296b0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
296c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
296d0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
296e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
296f0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
29700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
29710 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
29720 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
29730 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29740 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
29750 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65  CAPI3REF: Obsole
29760 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  te Functions.**.
29770 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
29780 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f  ns are all now o
29790 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64  bsolete.  In ord
297a0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
297b0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
297c0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
297d0 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f  lder code, we co
297e0 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72  ntinue to suppor
297f0 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  t.** these funct
29800 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  ions.  However, 
29810 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20  new development 
29820 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20  projects should 
29830 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
29840 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
29850 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
29860 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
29870 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
29880 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
29890 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
298a0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
298b0 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  ant they do..*/.
298c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
298d0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
298e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69  te3_context*);.i
298f0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
29900 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
29910 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  );.int sqlite3_t
29920 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
29930 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
29950 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
29960 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
29970 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  ;.void sqlite3_t
29980 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
29990 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
299a0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
299b0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
299c0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
299d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
299e0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
299f0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
29a00 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
29a10 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46  ameter Values {F
29a20 31 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  15100}.**.** The
29a30 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
29a40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
29a50 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
29a60 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
29a70 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
29a80 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
29a90 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
29aa0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
29ab0 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
29ac0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
29ad0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
29ae0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
29af0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
29b00 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
29b10 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
29b20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
29b30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
29b40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
29b50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
29b60 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
29b70 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
29b80 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
29b90 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
29ba0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
29bb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29bc0 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
29bd0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
29be0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
29bf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29c00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
29c10 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
29c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29c30 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
29c40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
29c50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
29c60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
29c70 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
29c80 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
29c90 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
29ca0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
29cb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
29cc0 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
29cd0 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
29ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29cf0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
29d00 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
29d10 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
29d20 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
29d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
29d40 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
29d50 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
29d60 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  avior..**.** The
29d70 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
29d80 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
29d90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a  orresponding .**
29da0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29db0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
29dc0 63 6f 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65  column_* routine
29dd0 73 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 0a  s] except that .
29de0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
29df0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
29e00 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
29e10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
29e20 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74   pointer.** inst
29e30 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
29e40 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
29e50 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
29e60 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
29e70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29e80 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
29e90 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
29ea0 74 73 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  ts a UTF16 strin
29eb0 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
29ec0 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
29ed0 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
29ee0 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  e.  The.** sqlit
29ef0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
29f00 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
29f10 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
29f20 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
29f30 78 74 72 61 63 74 20 55 54 46 31 36 20 73 74 72  xtract UTF16 str
29f40 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
29f50 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
29f60 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
29f70 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
29f80 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
29f90 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
29fa0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
29fb0 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
29fc0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
29fd0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
29fe0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
29ff0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
2a000 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2a010 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
2a020 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
2a030 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
2a040 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
2a050 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
2a060 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
2a070 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
2a080 2a 2a 20 77 6f 72 64 73 20 69 66 20 74 68 65 20  ** words if the 
2a090 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
2a0a0 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
2a0b0 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
2a0c0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
2a0d0 6f 6e 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68  on is done.  Oth
2a0e0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2a0f0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68  sion occurs.  Th
2a100 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e .** [SQLITE_IN
2a110 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2a120 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
2a130 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  on is returned..
2a140 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2a150 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2a160 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2a170 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2a180 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65  er that.** is re
2a190 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2a1a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2a1b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2a1c0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
2a1d0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2a1e0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
2a1f0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
2a200 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
2a210 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2a220 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2a230 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2a240 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
2a250 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a260 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2a270 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2a280 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].  .**.** The
2a290 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2a2a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2a2b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2a2c0 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2a2d0 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2a2e0 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2a2f0 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2a300 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49  ters..**.**.** I
2a310 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2a320 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73   {F15103} The [s
2a330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2a340 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  b(V)] interface 
2a350 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a360 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2a370 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a380 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2a390 20 61 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e   a blob and then
2a3a0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
2a3b0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
2a3c0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
2a3d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
2a3e0 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5106} The [sqlit
2a3f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56  e3_value_bytes(V
2a400 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2a410 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2a420 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2a430 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62  ytes in the blob
2a440 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
2a450 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2a460 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2a470 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2a480 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2a490 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2a4b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2a4c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2a4d0 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20  blob(V)] or.**  
2a4e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2a4f0 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e  _value_text(V)].
2a500 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20  .**.** {F15109} 
2a510 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2a520 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69  ue_bytes16(V)] i
2a530 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a540 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a550 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a560 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28   in the string (
2a570 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2a580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2a590 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
2a5a0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
2a5b0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
2a5c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a5d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2a5e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
2a5f0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a  lue_text16(V)],.
2a600 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a610 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a620 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c  6be(V)], or [sql
2a630 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a640 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6le(V)]..**.** {
2a650 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  F15112} The [sql
2a660 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2a670 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2a680 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a690 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2a6a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a6b0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2a6c0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2a6d0 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20  t value and.**  
2a6e0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2a6f0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
2a700 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  alue..**.** {F15
2a710 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  115} The [sqlite
2a720 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20  3_value_int(V)] 
2a730 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a740 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a750 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2a760 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a770 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d  ect V into a 64-
2a780 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2a790 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
2a7a0 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c     returns the l
2a7b0 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20  ower 32 bits of 
2a7c0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
2a7d0 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65  .** {F15118} The
2a7e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2a7f0 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66  int64(V)] interf
2a800 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2a810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2a820 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a830 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2a840 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2a850 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2a860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2a870 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2a880 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
2a890 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20  ** {F15121} The 
2a8a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2a8b0 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ext(V)] interfac
2a8c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2a8d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2a8e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a8f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2a900 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2a910 61 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20  ated UTF-8 .**  
2a920 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2a930 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2a940 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2a950 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
2a960 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2a970 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29  _value_text16(V)
2a980 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2a990 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2a9a0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2a9b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a9c0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2a9d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2a9e0 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2a9f0 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2aa00 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2aa10 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
2aa20 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2aa30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2aa40 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2aa50 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b  * {F15127} The [
2aa60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2aa70 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72  xt16be(V)] inter
2aa80 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2aa90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2aaa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2aab0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2aac0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2aad0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2aae0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2aaf0 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  ed UTF-16 big-en
2ab00 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2ab10 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ab20 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ab30 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ab40 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65  .** {F15130} The
2ab50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ab60 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74  text16le(V)] int
2ab70 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2ab80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ab90 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2aba0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2abb0 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2abc0 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2abd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2abe0 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74  gned UTF-16 litt
2abf0 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
2ac00 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2ac10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ac20 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2ac30 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33  g..**.** {F15133
2ac40 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2ac50 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e  alue_type(V)] in
2ac60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2ac70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
2ac80 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2ac90 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
2aca0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2acb0 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
2acc0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2acd0 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
2ace0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2acf0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2ad00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2ad10 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a  e] object V..**.
2ad20 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20  ** {F15136} The 
2ad30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e  [sqlite3_value_n
2ad40 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20  umeric_type(V)] 
2ad50 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2ad60 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ts.**          t
2ad70 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  he [protected sq
2ad80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ad90 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65  ect V into eithe
2ada0 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a  r an integer or.
2adb0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 6c  **          a fl
2adc0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2add0 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20  ue if it can do 
2ade0 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  so without loss 
2adf0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  of.**          i
2ae00 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20  nformation, and 
2ae10 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b  returns one of [
2ae20 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a  SQLITE_NULL],.**
2ae30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2ae40 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2ae50 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2ae60 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a  ITE_TEXT], or.**
2ae70 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2ae80 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2ae90 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2aea0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
2aeb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2aec0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66  lue] object V af
2aed0 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ter the conversi
2aee0 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63  on attempt..*/.c
2aef0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2af00 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2af10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2af20 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2af30 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2af40 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2af50 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2af60 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2af70 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2af80 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2af90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2afa0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2afb0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2afc0 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2afd0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2afe0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2aff0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2b000 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2b010 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2b020 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2b030 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2b050 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2b060 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2b070 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2b080 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2b090 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2b0a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2b0b0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2b0c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2b0d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2b0e0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2b0f0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2b100 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2b110 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2b120 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2b130 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2b140 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2b150 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d  Context {F16210}
2b160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
2b170 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
2b180 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2b190 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
2b1a0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2b1b0 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
2b1c0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2b1d0 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54  ir state.  .** T
2b1e0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2b1f0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2b200 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f  ate_context() ro
2b210 75 74 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63  utine is.** is c
2b220 61 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74  alled for a part
2b230 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2b240 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
2b250 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
2b260 6f 72 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61  ory.** zeros tha
2b270 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2b280 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b290 74 6f 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63  to it..** On sec
2b2a0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2b2b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  nt calls to sqli
2b2c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2b2d0 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74  ntext().** for t
2b2e0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2b2f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
2b300 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  , the same buffe
2b310 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2b320 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
2b330 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61  tion.** of the a
2b340 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
2b350 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
2b360 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
2b370 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  te data..**.** S
2b380 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2b390 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c  lly frees the al
2b3a0 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77  located buffer w
2b3b0 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2b3c0 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
2b3d0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
2b3e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2b3f0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
2b400 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   of the .** [sql
2b410 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
2b420 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
2b430 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
2b440 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
2b450 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
2b460 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
2b470 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2b480 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
2b490 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2b4a0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2b4b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2b4c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2b4d0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
2b4e0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2b4f0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2b500 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2b510 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31  S:.**.** {F16211
2b520 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f  } The first invo
2b530 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
2b540 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2b550 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a  text(C,N)] for.*
2b560 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72  *          a par
2b570 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
2b580 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65   of an aggregate
2b590 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61   function (for a
2b5a0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20   particular.**  
2b5b0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
2b5c0 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  C) causes SQLite
2b5d0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e   to allocation N
2b5e0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
2b5f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  ,.**          ze
2b600 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ro that memory, 
2b610 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
2b620 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f  nter to the allo
2b630 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  cated.**        
2b640 20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20    memory..**.** 
2b650 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {F16213} If a me
2b660 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2b670 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2b680 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2b690 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2b6a0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2b6b0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2b6c0 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2b6d0 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63  .** {F16215} Sec
2b6e0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2b6f0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2b700 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2b710 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2b720 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2b730 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2b740 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2b750 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2b760 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2b770 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2b780 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2b790 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2b7a0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2b7b0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2b7c0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2b7d0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54  **.** {F16217} T
2b7e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2b7f0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2b800 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2b810 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2b820 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2b830 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2b840 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2b850 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2b870 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b880 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2b890 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b8a0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2b8b0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2b8c0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2b8d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b8e0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2b8f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2b900 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2b910 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2b920 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2b930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2b940 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2b950 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a  tions {F16240}.*
2b960 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b970 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2b980 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b990 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2b9a0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2b9b0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2b9c0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2b9d0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2b9e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b9f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ba00 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2ba10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ba20 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2ba30 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2ba40 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2ba50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ba60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2ba70 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2ba80 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2ba90 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2baa0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2bab0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
2bac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bad0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
2bae0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2baf0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2bb00 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c  F16243} The [sql
2bb10 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43  ite3_user_data(C
2bb20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2bb30 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2bb40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50  he.**          P
2bb50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2bb60 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2bb70 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2bb80 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2bb90 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2bba0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bbb0 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2bbc0 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2bbd0 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2bbe0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2bbf0 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2bc00 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20  iated with .**  
2bc10 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2bc20 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
2bc30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
2bc40 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
2bc50 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
2bc60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
2bc70 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
2bc80 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  For Functions {F
2bc90 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16250}.**.** The
2bca0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2bcb0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2bcc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2bcd0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2bce0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2bcf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bd00 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2bd10 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2bd20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2bd30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2bd40 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2bd50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2bd60 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2bd70 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2bd80 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2bd90 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2bda0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
2bdb0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2bdc0 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54 68  *.** {F16253} Th
2bdd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2bde0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d  xt_db_handle(C)]
2bdf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2be00 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2be10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70  .**          D p
2be20 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
2be30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2be40 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2be50 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2be60 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2be70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2be80 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
2be90 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
2bea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2beb0 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
2bec0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2bed0 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20  ted with .**    
2bee0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2bef0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
2bf00 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2bf10 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2bf20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2bf30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2bf40 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2bf50 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31  xiliary Data {F1
2bf60 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6270}.**.** The 
2bf70 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
2bf80 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
2bf90 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
2bfa0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
2bfb0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
2bfc0 2d 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d  -data with argum
2bfd0 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74  ent values. If t
2bfe0 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73  he same value is
2bff0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75   passed to.** mu
2c000 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f  ltiple invocatio
2c010 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53  ns of the same S
2c020 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69  QL function duri
2c030 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69  ng query executi
2c040 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d  on, under.** som
2c050 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
2c060 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d  the associated m
2c070 65 74 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20  eta-data may be 
2c080 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
2c090 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
2c0a0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
2c0b0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
2c0c0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
2c0d0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
2c0e0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
2c0f0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
2c100 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2c110 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
2c120 73 0a 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61  s.** meta-data a
2c130 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2c140 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
2c150 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
2c160 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
2c170 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
2c180 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
2c190 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
2c1a0 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
2c1b0 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
2c1c0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2c1d0 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
2c1e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
2c1f0 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
2c200 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2c210 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
2c220 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
2c230 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
2c240 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2c250 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2c260 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c270 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
2c280 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
2c290 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
2c2a0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
2c2b0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
2c2c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
2c2d0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
2c2e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2c2f0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f  nction..** If no
2c300 20 6d 65 74 61 2d 64 61 74 61 20 68 61 73 20 62   meta-data has b
2c310 65 65 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65  een ever been se
2c320 74 20 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a  t for the Nth.**
2c330 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2c340 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
2c350 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2c360 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
2c370 6d 65 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61  meter.** has cha
2c380 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
2c390 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
2c3a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  , then sqlite3_g
2c3b0 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20  et_auxdata().** 
2c3c0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2c3d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
2c3e0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2c3f0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2c400 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2c410 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  -data.** pointed
2c420 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2c430 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2c440 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68  meta-data for th
2c450 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
2c460 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
2c470 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2c480 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
2c490 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2c4a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2c4b0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
2c4c0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
2c4d0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
2c4e0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a  een destroyed. .
2c4f0 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
2c500 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
2c510 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2c520 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63  tructor .** func
2c530 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
2c540 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2c550 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
2c560 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
2c570 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65  he meta-data whe
2c580 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
2c590 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
2c5a0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
2c5b0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
2c5c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2c5d0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
2c5e0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
2c5f0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
2c600 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
2c610 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
2c620 6f 70 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a  op meta-data on.
2c630 2a 2a 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72  ** any parameter
2c640 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2c650 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
2c660 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2c670 65 0a 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65  e.** is that the
2c680 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2c690 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2c6a0 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2c6b0 73 0a 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  s.** dropped..**
2c6c0 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c  .** In practice,
2c6d0 20 6d 65 74 61 2d 64 61 74 61 20 69 73 20 70 72   meta-data is pr
2c6e0 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
2c6f0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
2c700 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
2c710 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
2c720 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
2c730 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
2c740 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
2c750 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72  lues and SQL var
2c760 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  iables..**.** Th
2c770 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2c780 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2c790 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2c7a0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2c7b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2c7c0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2c7d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2c7e0 2a 20 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b  * {F16272} The [
2c7f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2c800 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  ata(C,N)] interf
2c810 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2c820 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
2c830 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73    to metadata as
2c840 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2c850 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2c860 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2c870 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
2c880 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73  whose context is
2c890 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74   C, or NULL if t
2c8a0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
2c8b0 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ata associated.*
2c8c0 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
2c8d0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  that parameter..
2c8e0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54  **.** {F16274} T
2c8f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
2c900 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
2c910 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73 73 69  ] interface assi
2c920 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a  gns a metadata.*
2c930 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2c940 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20  er P to the Nth 
2c950 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2c960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69   SQL function wi
2c970 74 68 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  th context.**   
2c980 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20         C..**.** 
2c990 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {F16276} SQLite 
2c9a0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2c9b0 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
2c9c0 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
2c9d0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
2c9e0 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
2c9f0 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
2ca00 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
2ca10 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2ca20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2ca30 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
2ca40 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
2ca50 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
2ca60 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
2ca70 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  ta..**.** {F1627
2ca80 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
2ca90 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
2caa0 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
2cab0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
2cac0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
2cad0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2cae0 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
2caf0 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nges..**.** {F16
2cb00 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
2cb10 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2cb20 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
2cb30 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
2cb40 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
2cb50 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
2cb60 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
2cb70 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2cb80 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2cb90 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
2cba0 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
2cbb0 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
2cbc0 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {F16279} SQLite 
2cbd0 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
2cbe0 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
2cbf0 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
2cc00 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
2cc10 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
2cc20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cc30 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
2cc40 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
2cc50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2cc60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2cc70 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
2cc80 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
2cc90 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2cca0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2ccb0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
2ccc0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
2ccd0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2cce0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
2ccf0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
2cd00 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
2cd10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
2cd20 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
2cd30 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
2cd40 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38   Behavior {F1028
2cd50 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  0}.**.** These a
2cd60 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  re special value
2cd70 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
2cd80 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
2cd90 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
2cda0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
2cdb0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2cdc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2cdd0 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
2cde0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
2cdf0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
2ce00 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
2ce10 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2ce20 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
2ce30 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
2ce40 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
2ce50 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
2ce60 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
2ce70 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51  yed.  The .** SQ
2ce80 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
2ce90 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
2cea0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
2ceb0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
2cec0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
2ced0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
2cee0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
2cef0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2cf00 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2cf10 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
2cf20 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
2cf30 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
2cf40 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
2cf50 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
2cf60 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
2cf70 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
2cf80 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
2cf90 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
2cfa0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
2cfb0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
2cfc0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
2cfd0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
2cfe0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2cff0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
2d000 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
2d010 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
2d020 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2d030 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
2d040 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
2d050 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
2d060 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36  QL Function {F16
2d070 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
2d080 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2d090 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
2d0a0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2d0b0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
2d0c0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
2d0d0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2d0e0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
2d0f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d100 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2d110 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d120 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
2d130 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2d140 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
2d150 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
2d160 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
2d170 6b 65 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  ke the .** [sqli
2d180 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2d190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20  sqlite3_bind_*] 
2d1a0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
2d1b0 6f 6e 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62  ons used.** to b
2d1c0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
2d1d0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
2d1e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d1f0 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
2d200 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  o the.** [sqlite
2d210 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2d220 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63  lite3_bind_* doc
2d230 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a  umentation] for.
2d240 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
2d250 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2d260 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2d270 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
2d280 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2d290 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2d2a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d2b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2d2c0 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
2d2d0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
2d2e0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
2d2f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2d300 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
2d310 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
2d320 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
2d330 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2d340 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d350 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2d360 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
2d370 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2d380 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2d390 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2d3a0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
2d3b0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
2d3c0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
2d3d0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
2d3e0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2d3f0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
2d400 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2d410 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d420 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
2d430 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2d440 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2d450 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2d460 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2d470 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
2d480 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
2d490 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
2d4a0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
2d4b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d4c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2d4d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2d4e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
2d4f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
2d500 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
2d510 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2d520 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
2d530 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ion..** SQLite u
2d540 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
2d550 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2d560 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
2d570 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
2d580 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
2d590 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d5a0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
2d5b0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
2d5c0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c  or message.  SQL
2d5d0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
2d5e0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2d5f0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
2d600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2d610 72 72 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20  rror() as UTF8. 
2d620 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2d630 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2d640 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2d650 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2d660 20 55 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65   UTF16 in native
2d670 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
2d680 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
2d690 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d6a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2d6b0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2d6c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2d6d0 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
2d6e0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
2d6f0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2d700 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
2d710 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2d720 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2d730 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74  ter..** If the t
2d740 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2d750 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2d760 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
2d770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2d780 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
2d790 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2d7a0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
2d7b0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
2d7c0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
2d7d0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2d7e0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
2d7f0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68  r message..** Th
2d800 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2d810 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
2d820 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d830 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
2d840 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72  s make a copy pr
2d850 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2d860 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2d870 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
2d880 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
2d890 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
2d8a0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
2d8b0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
2d8c0 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
2d8d0 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
2d8e0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2d8f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2d900 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2d910 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2d920 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2d930 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2d940 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2d950 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2d960 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42  n a function.  B
2d970 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
2d980 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
2d990 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41  SQLITE_ERROR.  A
2d9a0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2d9b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2d9c0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2d9d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d9e0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
2d9f0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
2da00 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
2da10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2da20 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
2da30 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
2da40 73 65 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f  ses SQLite.** to
2da50 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20   throw an error 
2da60 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
2da70 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
2da80 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74   is to long.** t
2da90 6f 20 72 65 70 72 65 73 65 6e 74 2e 20 20 54 68  o represent.  Th
2daa0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2dab0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
2dac0 63 65 0a 2a 2a 20 63 61 75 73 65 73 20 53 51 4c  ce.** causes SQL
2dad0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2dae0 65 78 63 65 70 74 69 6f 6e 20 69 6e 64 69 63 61  exception indica
2daf0 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 0a  ting that the a.
2db00 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
2db10 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
2db20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2db30 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
2db40 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2db50 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2db60 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2db70 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2db80 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
2db90 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2dba0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2dbb0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2dbc0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
2dbd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2dbe0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
2dbf0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2dc00 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2dc10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dc20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2dc30 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
2dc40 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2dc50 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2dc60 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2dc70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2dc80 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
2dc90 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2dca0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2dcb0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2dcc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2dcd0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
2dce0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
2dcf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2dd00 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
2dd10 6c 74 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a  lt_text16(), .**
2dd20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2dd30 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
2dd40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2dd50 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
2dd60 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
2dd70 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2dd80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2dd90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2dda0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
2ddb0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2ddc0 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
2ddd0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
2dde0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2ddf0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2de00 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
2de10 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
2de20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2de30 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2de40 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2de50 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2de60 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2de70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2de80 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2de90 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2dea0 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
2deb0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2dec0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2ded0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2dee0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2def0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2df00 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2df10 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2df20 61 72 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72  arameter .** thr
2df30 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2df40 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2df50 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
2df60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2df70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2df80 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2df90 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2dfa0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2dfb0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2dfc0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2dfd0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2dfe0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2dff0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2e000 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2e010 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2e020 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2e030 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2e040 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2e050 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2e060 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2e070 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2e080 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
2e090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2e0a0 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
2e0b0 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
2e0c0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
2e0d0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
2e0e0 72 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68  r blob result wh
2e0f0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
2e100 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2e110 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
2e120 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2e130 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2e140 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2e150 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2e160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2e170 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2e180 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2e190 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a  _STATIC, then.**
2e1a0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2e1b0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
2e1c0 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 69 73 20   blob result is 
2e1d0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
2e1e0 6e 64 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63  nd.** does not c
2e1f0 6f 70 79 20 74 68 65 20 73 70 61 63 65 20 6f 72  opy the space or
2e200 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
2e210 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  or when it has.*
2e220 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2e230 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2e240 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2e250 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2e260 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2e270 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2e280 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2e290 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2e2a0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2e2b0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
2e2c0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
2e2d0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2e2e0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
2e2f0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
2e300 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
2e310 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
2e320 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
2e330 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2e340 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2e350 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2e360 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2e370 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2e380 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e390 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
2e3a0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
2e3b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e3c0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
2e3d0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
2e3e0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
2e3f0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2e400 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2e410 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
2e420 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2e430 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
2e440 74 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t [sqlite3_value
2e450 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
2e460 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
2e470 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
2e480 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
2e490 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
2e4a0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
2e4b0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
2e4c0 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
2e4d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e4e0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
2e4f0 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
2e500 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2e510 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2e520 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
2e530 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
2e540 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
2e550 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e560 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
2e570 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
2e580 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
2e590 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2e5a0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
2e5b0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
2e5c0 68 72 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74  hread .** than t
2e5d0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
2e5e0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
2e5f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e600 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
2e610 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2e620 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
2e630 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
2e640 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2e650 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2e660 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54  **.** {F16403} T
2e670 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72  he default retur
2e680 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79  n value from any
2e690 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2e6a0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   NULL..**.** {F1
2e6b0 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  6406} The [sqlit
2e6c0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
2e6d0 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
2e6e0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2e6f0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2e700 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2e710 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 62 6c  ion C to be a bl
2e720 6f 62 20 74 68 61 74 20 69 73 20 4e 20 62 79 74  ob that is N byt
2e730 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  es.**          i
2e740 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74  n length and wit
2e750 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  h content pointe
2e760 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a  d to by V..**.**
2e770 20 7b 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73   {F16409} The [s
2e780 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2e790 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72  uble(C,V)] inter
2e7a0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2e7b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2e7c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
2e7d0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
2e7e0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2e7f0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
2e800 7b 46 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71  {F16412} The [sq
2e810 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e820 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72  or(C,V,N)] inter
2e830 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
2e840 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
2e850 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e      value of fun
2e860 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
2e870 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
2e880 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
2e890 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
2e8a0 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 38  RROR] and a UTF8
2e8b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
2e8c0 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
2e8d0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
2e8e0 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
2e8f0 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
2e900 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
2e910 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
2e920 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68  *.** {F16415} Th
2e930 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2e940 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
2e950 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2e960 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
2e970 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
2e980 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2e990 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
2e9a0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
2e9b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
2e9c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
2e9d0 20 61 20 55 54 46 31 36 20 6e 61 74 69 76 65 20   a UTF16 native 
2e9e0 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72  byte order error
2e9f0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
2ea00 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d       copied from
2ea10 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
2ea20 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2ea30 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  or or until N by
2ea40 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
2ea50 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73  are read if N is
2ea60 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   positive..**.**
2ea70 20 7b 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73   {F16418} The [s
2ea80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ea90 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69  ror_toobig(C)] i
2eaa0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
2eab0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
2eac0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
2ead0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
2eae0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
2eaf0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
2eb00 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
2eb10 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61  SQLITE_TOOBIG] a
2eb20 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
2eb30 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2eb40 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20  .**.** {F16421} 
2eb50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2eb60 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
2eb70 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
2eb80 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
2eb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
2eba0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
2ebb0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
2ebc0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
2ebd0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
2ebe0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45      [SQLITE_NOME
2ebf0 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  M] and an approp
2ec00 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
2ec10 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  age..**.** {F164
2ec20 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2ec30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
2ec40 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61  de(C,E)] interfa
2ec50 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
2ec60 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
2ec70 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
2ec80 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2ec90 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
2eca0 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a  h error code E..
2ecb0 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20  **          The 
2ecc0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2ecd0 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  xt is unchanged.
2ece0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20  .**.** {F16427} 
2ecf0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2ed00 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e  ult_int(C,V)] in
2ed10 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2ed20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2ed30 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2ed40 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2ed50 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65   the 32-bit inte
2ed60 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  ger value V..**.
2ed70 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20  ** {F16430} The 
2ed80 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2ed90 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65  int64(C,V)] inte
2eda0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
2edb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
2edc0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
2edd0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
2ede0 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  he 64-bit intege
2edf0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
2ee00 20 7b 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73   {F16433} The [s
2ee10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2ee20 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ll(C)] interface
2ee30 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
2ee40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
2ee50 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
2ee60 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  n C to be NULL..
2ee70 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54  **.** {F16436} T
2ee80 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
2ee90 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
2eea0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
2eeb0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
2eec0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
2eed0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
2eee0 6f 20 62 65 20 74 68 65 20 55 54 46 38 20 73 74  o be the UTF8 st
2eef0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
2ef00 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
2ef10 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
2ef20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
2ef30 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
2ef40 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
2ef50 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
2ef60 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
2ef70 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  39} The [sqlite3
2ef80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
2ef90 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
2efa0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
2efb0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2efc0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
2efd0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
2efe0 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79 74  UTF16 native byt
2eff0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
2f000 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
2f010 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2f020 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20  o if N is.**    
2f030 20 20 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f        negative o
2f040 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
2f050 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
2f060 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
2f070 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68  *.** {F16442} Th
2f080 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2f090 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
2f0a0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
2f0b0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2f0c0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2f0d0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2f0e0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 31  C to be the UTF1
2f0f0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
2f100 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2f110 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
2f120 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
2f130 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 65  *          is ne
2f140 67 61 74 69 76 65 20 6f 72 20 74 68 65 20 66 69  gative or the fi
2f150 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56  rst N bytes or V
2f160 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
2f170 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
2f180 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6445} The [sqlit
2f190 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2f1a0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  le(C,V,N,D)] int
2f1b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
2f1c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
2f1d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
2f1e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
2f1f0 74 68 65 20 55 54 46 31 36 20 6c 69 74 74 6c 65  the UTF16 little
2f200 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
2f210 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
2f220 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2f230 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20  o if N is.**    
2f240 20 20 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f        negative o
2f250 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
2f260 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
2f270 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
2f280 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68  *.** {F16448} Th
2f290 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2f2a0 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e  t_value(C,V)] in
2f2b0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
2f2c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f2d0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2f2e0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
2f2f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f300 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2f310 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
2f320 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31  V..**.** {F16451
2f330 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2f340 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43  esult_zeroblob(C
2f350 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2f360 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
2f370 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
2f380 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
2f390 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74  C to be an N-byt
2f3a0 65 20 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65  e blob of all ze
2f3b0 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ros..**.** {F164
2f3c0 35 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  54} The [sqlite3
2f3d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d  _result_error()]
2f3e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2f3f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a  sult_error16()].
2f400 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2f410 72 66 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f  rfaces make a co
2f420 70 79 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f  py of their erro
2f430 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2f440 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20  s before.**     
2f450 20 20 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a       returning..
2f460 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49  **.** {F16457} I
2f470 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
2f480 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
2f490 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2f4a0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
2f4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2f4c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f4d0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
2f4e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2f4f0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
2f500 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2f510 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2f520 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
2f530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2f540 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f550 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
2f560 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20  is the constant 
2f570 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a  [SQLITE_STATIC].
2f580 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2f590 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69   no destructor i
2f5a0 73 20 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e  s ever called on
2f5b0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61   the pointer V a
2f5c0 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  nd SQLite.**    
2f5d0 20 20 20 20 20 20 61 73 73 75 6d 65 73 20 74 68        assumes th
2f5e0 61 74 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c  at V is immutabl
2f5f0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30  e..**.** {F16460
2f600 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
2f610 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
2f620 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2f630 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
2f640 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2f650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f660 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
2f670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f680 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
2f690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2f6a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f6b0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
2f6c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2f6d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2f6e0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
2f6f0 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
2f700 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nt.**          [
2f710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2f720 5d 20 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72  ] then the inter
2f730 66 61 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f  faces makes a co
2f740 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2f750 20 20 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66        content of
2f760 20 56 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74   V and retains t
2f770 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b  he copy..**.** {
2f780 46 31 36 34 36 33 7d 20 49 66 20 74 68 65 20 44  F16463} If the D
2f790 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
2f7a0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2f7b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
2f7c0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
2f7d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2f7e0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
2f7f0 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
2f800 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
2f810 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
2f820 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
2f830 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
2f840 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
2f850 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2f860 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
2f870 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65  ,V,N,D)] is some
2f880 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
2f890 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
2f8a0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
2f8b0 49 54 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20  ITE_STATIC] and 
2f8c0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2f8d0 54 5d 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20  T] then .**     
2f8e0 20 20 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c       SQLite will
2f8f0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
2f900 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 56 20  ructor D with V 
2f910 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75  as its only argu
2f920 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
2f930 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2f940 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 56  ished with the V
2f950 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20   value..*/.void 
2f960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2f970 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2f980 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2f990 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2f9a0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2f9b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2f9c0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
2f9d0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
2f9e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2f9f0 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2fa00 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2fa10 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
2fa20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2fa30 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
2fa40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2fa50 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
2fa60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2fa70 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2fa80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fa90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2faa0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2fab0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
2fac0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2fad0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2fae0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
2faf0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2fb00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fb10 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
2fb20 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2fb30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fb40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
2fb50 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2fb60 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
2fb70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2fb80 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
2fb90 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2fba0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
2fbb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fbc0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2fbd0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2fbe0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fbf0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
2fc00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fc10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2fc20 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2fc30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fc40 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2fc50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fc60 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2fc70 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2fc80 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2fc90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2fca0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fcb0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2fcc0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2fcd0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2fce0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
2fcf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fd00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2fd10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2fd20 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
2fd30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fd40 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2fd50 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
2fd60 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
2fd70 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30  equences {F16600
2fd80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  }.**.** These fu
2fd90 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
2fda0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
2fdb0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2fdc0 74 6f 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  to the.** [sqlit
2fdd0 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63  e3*] handle spec
2fde0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2fdf0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a  st argument. .**
2fe00 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
2fe10 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
2fe20 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
2fe30 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
2fe40 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
2fe50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fe60 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
2fe70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2fe80 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
2fe90 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
2fea0 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
2feb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2fec0 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61  n16(). In all ca
2fed0 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
2fee0 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
2fef0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2ff00 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2ff10 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2ff20 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
2ff30 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
2ff40 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2ff50 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
2ff60 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  E] or [SQLITE_UT
2ff70 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
2ff80 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
2ff90 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
2ffa0 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
2ffb0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
2ffc0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
2ffd0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
2ffe0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
2fff0 74 6c 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54  tle-endian or UT
30000 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20  F-16 big-endian 
30010 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
30020 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
30030 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
30040 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
30050 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
30060 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
30070 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
30080 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
30090 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
300a0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
300b0 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  TF16 in the nati
300c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66  ve byte order of
300d0 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
300e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  er..**.** A poin
300f0 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20  ter to the user 
30100 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
30110 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
30120 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20  as the fifth.** 
30130 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74  argument.  If it
30140 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
30150 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
30160 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
30170 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
30180 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
30190 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
301a0 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63  anymore)..** Eac
301b0 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69  h time the appli
301c0 63 61 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  cation.** suppli
301d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
301e0 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
301f0 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
30200 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
30210 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68  as.** the fourth
30220 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
30230 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30240 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71  ation() or.** sq
30250 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30260 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74  lation16() as it
30270 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
30280 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  r..**.** The rem
30290 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
302a0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
302b0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
302c0 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
302d0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
302e0 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
302f0 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
30300 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
30310 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
30320 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
30330 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
30340 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
30350 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
30360 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
30370 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65  tered. {END} The
30380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
30390 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
303a0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
303b0 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
303c0 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
303d0 76 65 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72  ve if.** the fir
303e0 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73  st string is les
303f0 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f  s than, equal to
30400 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
30410 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  n the second.** 
30420 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54  string. i.e. (ST
30430 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29  RING1 - STRING2)
30440 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30450 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
30460 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
30470 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
30480 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
30490 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
304a0 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
304b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
304c0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
304d0 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
304e0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72  tion.  The destr
304f0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20  uctor is called 
30500 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
30510 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79  on is.** destroy
30520 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64  ed and is passed
30530 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
30540 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30550 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a  void* pointer.**
30560 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
30570 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30580 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74  _v2()..** Collat
30590 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
305a0 65 64 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20  ed when.** they 
305b0 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
305c0 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
305d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
305e0 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
305f0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
30600 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61   [sqlite3*] data
30610 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63  base handle is c
30620 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
30630 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
30640 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
30650 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20  .**.** {F16603} 
30660 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
30670 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  l to the.**     
30680 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
30690 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
306a0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20  2(B,X,E,P,F,D)] 
306b0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20  interface.**    
306c0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20        registers 
306d0 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68  function F as th
306e0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
306f0 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a  ction used to.**
30700 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d            implem
30710 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20  ent collation X 
30720 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
30730 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
30740 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
30750 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
30760 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ding E..**.** {F
30770 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
30780 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
30790 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
307a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
307b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
307c0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
307d0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
307e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
307f0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
30800 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
30810 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
30820 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
30830 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
30840 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
30850 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
30860 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
30870 46 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  F16606} Successi
30880 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
30890 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
308a0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
308b0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
308c0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
308d0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
308e0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
308f0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
30900 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
30910 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
30920 20 7b 46 31 36 36 30 39 7d 20 54 68 65 20 64 65   {F16609} The de
30930 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73  structor D in [s
30940 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
30950 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
30960 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
30970 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c       is not NULL
30980 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c   then it is call
30990 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
309a0 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20   P when the.**  
309b0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
309c0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
309d0 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e  opped by SQLite.
309e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20  .**.** {F16612} 
309f0 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
30a00 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
30a10 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c  when it is overl
30a20 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  oaded..**.** {F1
30a30 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6615} A collatin
30a40 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
30a50 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64  opped when the d
30a60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30a70 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
30a80 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
30a90 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
30aa0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d  ..**.** {F16618}
30ab0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69   The pointer P i
30ac0 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
30ad0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
30ae0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
30af0 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73           is pass
30b00 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
30b10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
30b20 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69  r to the compari
30b30 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
30b40 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
30b50 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
30b60 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a  vocations of F..
30b70 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41  **.** {F16621} A
30b80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30b90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30ba0 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69  on(B,X,E,P,F)] i
30bb0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
30bc0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
30bd0 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  s a call to [sql
30be0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30bf0 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68  ation_v2()] with
30c00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
30c10 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73   same parameters
30c20 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74   and a NULL dest
30c30 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ructor..**.** {F
30c40 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67  16624} Following
30c50 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61   a [sqlite3_crea
30c60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
30c70 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a  B,X,E,P,F,D)],.*
30c80 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
30c90 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61  e uses the compa
30ca0 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46  rison function F
30cb0 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f   for all text co
30cc0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
30cd0 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20       operations 
30ce0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
30cf0 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65  nection] B on te
30d00 78 74 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a  xt values that.*
30d10 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 20 74  *          use t
30d20 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71  he collating seq
30d30 75 65 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a  uence name X..**
30d40 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20 54 68 65  .** {F16627} The
30d50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30d60 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58  _collation16(B,X
30d70 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74  ,E,P,F)] works t
30d80 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
30d90 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f      as [sqlite3_
30da0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30db0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63  (B,X,E,P,F)] exc
30dc0 65 70 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ept that the.** 
30dd0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
30de0 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64  on name X is und
30df0 65 72 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31  erstood as UTF-1
30e00 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
30e10 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
30e20 20 20 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54     instead of UT
30e30 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  F-8..**.** {F166
30e40 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  30} When multipl
30e50 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  e comparison fun
30e60 63 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ctions are avail
30e70 61 62 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d  able for the sam
30e80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
30e90 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
30ea0 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73  , SQLite chooses
30eb0 20 74 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74   the one whose t
30ec0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
30ed0 20 20 20 20 20 20 20 20 20 72 65 71 75 69 72 65           require
30ee0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
30ef0 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  nt of conversion
30f00 20 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c   from the defaul
30f10 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  t.**          te
30f20 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  xt encoding of t
30f30 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
30f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30f50 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
30f60 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
30f70 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
30f80 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
30f90 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
30fa0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
30fb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
30fc0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
30fd0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
30fe0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
30ff0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
31000 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
31010 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
31020 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
31030 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
31040 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
31050 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
31060 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
31070 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
31080 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
31090 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
310a0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
310b0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
310c0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
310d0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
310e0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
310f0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
31100 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
31110 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
31120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31130 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
31140 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  ed Callbacks {F1
31150 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  6700}.**.** To a
31160 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
31170 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
31180 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
31190 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
311a0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
311b0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
311c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
311d0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
311e0 69 74 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ith the.** datab
311f0 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65  ase handle to be
31200 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
31210 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
31220 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31230 20 69 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e   is.** required.
31240 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75  .**.** If the fu
31250 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
31260 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
31270 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31280 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
31290 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
312a0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
312b0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
312c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
312d0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
312e0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b  oded in UTF-8. {
312f0 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74  F16703} If sqlit
31300 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
31310 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
31320 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72   the names.** ar
31330 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
31340 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
31350 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
31360 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65   A call to eithe
31370 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
31380 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74  places any exist
31390 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ing callback..**
313a0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
313b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
313c0 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
313d0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
313e0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
313f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
31400 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
31410 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
31420 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
31430 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
31440 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
31450 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
31460 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65  tabase.** handle
31470 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
31480 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
31490 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
314a0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  * [SQLITE_UTF16B
314b0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
314c0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
314d0 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20  ing the most.** 
314e0 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
314f0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
31500 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
31510 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54  n required..** T
31520 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
31530 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
31540 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
31550 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
31560 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uence..**.** The
31570 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
31580 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
31590 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
315a0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
315b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
315c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
315d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
315e0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
315f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
31600 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
31610 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  v2()]..**.** INV
31620 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
31630 46 31 36 37 30 32 7d 20 41 20 73 75 63 63 65 73  F16702} A succes
31640 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
31650 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31660 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a  needed(D,P,F)].*
31670 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
31680 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
31690 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29  _needed16(D,P,F)
316a0 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20  ] causes.**     
316b0 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
316c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
316d0 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62   to invoke callb
316e0 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73 74  ack F with first
316f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
31700 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
31710 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d  r it needs a com
31720 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
31730 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20   for a.**       
31740 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
31750 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f  uence that it do
31760 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75  es not know abou
31770 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34  t..**.** {F16704
31780 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66 75  } Each successfu
31790 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
317a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
317b0 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ded()] or.**    
317c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
317d0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
317e0 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  6()] overrides t
317f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69  he callback regi
31800 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
31810 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
31820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31830 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61  ion] by prior ca
31840 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  lls to either.**
31850 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
31860 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37  ace..**.** {F167
31870 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  06} The name of 
31880 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63 6f  the requested co
31890 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
318a0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a   passed in the.*
318b0 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20 70  *          4th p
318c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
318d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55  callback is in U
318e0 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c  TF-8 if the call
318f0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
31900 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64 20   was registered 
31910 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
31920 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
31930 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
31940 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20     is in UTF-16 
31950 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31960 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r if the callbac
31970 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  k was.**        
31980 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69    registered usi
31990 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
319a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
319b0 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74  ]..**.** .*/.int
319c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
319d0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
319e0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
319f0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
31a00 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
31a10 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
31a20 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
31a30 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
31a40 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
31a50 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
31a60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
31a70 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
31a80 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
31a90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
31aa0 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
31ab0 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
31ac0 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
31ad0 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
31ae0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
31af0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
31b00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
31b10 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
31b20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
31b30 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
31b40 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
31b50 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
31b60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
31b70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
31b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31b90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
31ba0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
31bb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
31bc0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
31bd0 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
31be0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
31bf0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
31c00 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
31c10 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
31c20 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
31c30 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
31c40 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
31c50 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
31c60 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
31c70 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
31c80 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
31c90 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
31ca0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
31cb0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
31cc0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
31cd0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
31ce0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
31cf0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
31d00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
31d10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31d20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
31d30 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
31d40 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
31d50 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
31d60 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
31d70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31d80 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65  EF:  Suspend Exe
31d90 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
31da0 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d  rt Time {F10530}
31db0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31dc0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
31dd0 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68  ion.** causes th
31de0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
31df0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
31e00 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
31e10 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
31e20 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
31e30 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
31e40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
31e50 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
31e60 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
31e70 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
31e80 72 65 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a  requests with .*
31e90 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
31ea0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
31eb0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
31ec0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
31ed0 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65  to .** the neare
31ee0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
31ef0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
31f00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
31f10 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75  ctually .** requ
31f20 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
31f30 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
31f40 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
31f50 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
31f60 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
31f70 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
31f80 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
31f90 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
31fa0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
31fb0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
31fc0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
31fd0 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20  ** {F10533} The 
31fe0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
31ff0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76  )] interface inv
32000 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a  okes the xSleep.
32010 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68  **          meth
32020 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
32030 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56  t [sqlite3_vfs|V
32040 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  FS] in order to.
32050 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70  **          susp
32060 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  end execution of
32070 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
32080 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74  ead for at least
32090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d  .**          M m
320a0 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a  illiseconds..**.
320b0 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54 68 65 20  ** {F10536} The 
320c0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
320d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
320e0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
320f0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  of.**          m
32100 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
32110 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65  leep actually re
32120 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f  quested of the o
32130 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20  perating.**     
32140 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69       system, whi
32150 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  ch might be larg
32160 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61  er than the para
32170 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20  meter M..*/.int 
32180 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
32190 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
321a0 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68  REF:  Name Of Th
321b0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
321c0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
321d0 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F10310}.**.** 
321e0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
321f0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
32200 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
32210 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
32220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
32230 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
32240 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
32250 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
32260 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
32270 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
32280 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
32290 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
322a0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
322b0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  s NULL pointer, 
322c0 74 68 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73  then SQLite does
322d0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
322e0 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d   appropriate tem
322f0 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64  porary.** file d
32300 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
32310 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
32320 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  o modify this va
32330 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61  riable once a da
32340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32350 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70  n.** has been op
32360 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74  ened.  It is int
32370 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
32380 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
32390 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
323a0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
323b0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
323c0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
323d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
323e0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
323f0 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20  call and remain 
32400 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61  unchanged therea
32410 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  fter..*/.SQLITE_
32420 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
32430 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
32440 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
32450 33 52 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53  3REF:  Test To S
32460 65 65 20 49 66 20 54 68 65 20 44 61 74 61 62 61  ee If The Databa
32470 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f  se Is In Auto-Co
32480 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31 32 39 33  mmit Mode {F1293
32490 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
324a0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
324b0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
324c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
324d0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
324e0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
324f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
32500 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
32510 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
32520 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
32530 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
32540 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66   is on.** by def
32550 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69  ault.  Autocommi
32560 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
32570 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
32580 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
32590 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
325a0 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
325b0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
325c0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
325d0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
325e0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
325f0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
32600 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
32610 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
32620 61 63 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20  actions (errors 
32630 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
32640 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
32650 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51  _IOERR], .** [SQ
32660 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
32670 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
32680 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
32690 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
326a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
326b0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
326c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
326d0 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
326e0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20  .** find out if 
326f0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
32700 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32710 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
32720 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
32730 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
32740 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
32750 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32760 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20 54 68 65  .** {F12931} The
32770 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
32780 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74  tocommit(D)] int
32790 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
327a0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20  on-zero or.**   
327b0 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74         zero if t
327c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
327d0 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72  nection] D is or
327e0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
327f0 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  ommit.**        
32800 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69    mode, respecti
32810 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  vely..**.** {F12
32820 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  932} Autocommit 
32830 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
32840 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fault..**.** {F1
32850 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2933} Autocommit
32860 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
32870 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75  d by a successfu
32880 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  l [BEGIN] statem
32890 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ent..**.** {F129
328a0 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  34} Autocommit m
328b0 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
328c0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
328d0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
328e0 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  BACK].**        
328f0 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20    statement..** 
32900 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
32910 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39  NS:.***.** {U129
32920 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74  36} If another t
32930 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
32940 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
32950 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
32960 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
32970 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
32980 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
32990 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
329a0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
329b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
329c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
329d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
329e0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
329f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32a00 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61  EF:  Find The Da
32a10 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
32a20 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
32a30 65 6d 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a  ement {F13120}.*
32a40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32a50 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
32a60 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  face.** returns 
32a70 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64  the [sqlite3*] d
32a80 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
32a90 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72  o which a.** [pr
32aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32ab0 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68  ] belongs..** Th
32ac0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
32ad0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
32ae0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a  lite3_db_handle.
32af0 2a 2a 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  ** is the same d
32b00 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
32b10 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66  hat was.** the f
32b20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
32b30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
32b40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
32b50 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74  ts variants.** t
32b60 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20  hat was used to 
32b70 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
32b80 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
32b90 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  t place..**.** I
32ba0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
32bb0 20 7b 46 31 33 31 32 33 7d 20 54 68 65 20 5b 73   {F13123} The [s
32bc0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
32bd0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
32be0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
32bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
32c00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32c10 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
32c20 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20  ated with.**    
32c30 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
32c40 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
32c50 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
32c60 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
32c70 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a  te3_stmt*);.../*
32c80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
32c90 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
32ca0 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
32cb0 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 35 30  allbacks {F12950
32cc0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
32cd0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
32ce0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
32cf0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
32d00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
32d10 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
32d20 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
32d30 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
32d40 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
32d50 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
32d60 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
32d70 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
32d80 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
32d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32da0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
32db0 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  n..** The sqlite
32dc0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
32dd0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
32de0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
32df0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
32e00 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
32e10 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
32e20 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
32e30 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
32e40 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
32e50 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
32e60 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
32e70 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
32e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32e90 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
32ea0 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61  n..** The pArg a
32eb0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
32ec0 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20  d through.** to 
32ed0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49  the callback.  I
32ee0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
32ef0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
32f00 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74  function .** ret
32f10 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
32f20 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
32f30 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
32f40 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
32f50 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
32f60 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
32f70 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
32f80 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61  , its.** pArg va
32f90 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
32fa0 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
32fb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
32fc0 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20  .** Registering 
32fd0 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
32fe0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
32ff0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  lback..**.** For
33000 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
33010 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
33020 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
33030 20 74 6f 20 68 61 76 65 20 62 65 65 6e 20 0a 2a   to have been .*
33040 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
33050 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
33060 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
33070 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
33080 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
33090 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
330a0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
330b0 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
330c0 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
330d0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
330e0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
330f0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
33100 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
33110 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
33120 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
33130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
33140 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  osed..** The rol
33150 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
33160 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
33170 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
33180 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  s.** rolled back
33190 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69   because a commi
331a0 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  t callback retur
331b0 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a  ned non-zero..**
331c0 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e   <todo> Check on
331d0 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a   this </todo>.**
331e0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65 78  .** These are ex
331f0 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72  perimental inter
33200 66 61 63 65 73 20 61 6e 64 20 61 72 65 20 73 75  faces and are su
33210 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e  bject to change.
33220 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
33230 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31  S:.**.** {F12951
33240 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
33250 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
33260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
33270 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
33280 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
33290 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
332a0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
332b0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
332c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
332d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d  transaction comm
332e0 69 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  its on [database
332f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
33300 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54  **.** {F12952} T
33310 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
33320 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
33330 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
33340 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20  s the P.**      
33350 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f      argument fro
33360 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
33370 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
33380 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  e .**          [
33390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
333a0 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c  ion ] D , or NUL
333b0 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63  L on the first c
333c0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
333d0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
333e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
333f0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
33400 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20 63 61  {F12953} Each ca
33410 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
33420 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76  ommit_hook()] ov
33430 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
33440 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
33450 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
33460 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
33470 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66 20 74  ** {F12954} If t
33480 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
33490 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
334a0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73  _hook(D,F,P)] is
334b0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
334c0 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69    then the commi
334d0 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
334e0 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20  is canceled and 
334f0 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
33500 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
33510 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
33520 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a  ction commits..*
33530 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66  *.** {F12955} If
33540 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c   the commit call
33550 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
33560 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63  -zero then the c
33570 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20  ommit is.**     
33580 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69       converted i
33590 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
335a0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54  **.** {F12961} T
335b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
335c0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
335d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
335e0 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
335f0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
33600 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
33610 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
33620 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
33630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
33640 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73  ransaction rolls
33650 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61   back on [databa
33660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
33670 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d  ..**.** {F12962}
33680 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f   The [sqlite3_ro
33690 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
336a0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
336b0 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20  turns the P.**  
336c0 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
336d0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
336e0 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65  us call with the
336f0 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20   same .**       
33700 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
33710 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72  nection ] D , or
33720 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
33730 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
33740 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
33750 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20 63  ular [database c
33760 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
33770 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63  .** {F12963} Eac
33780 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
33790 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
337a0 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
337b0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
337c0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
337d0 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
337e0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34  s..**.** {F12964
337f0 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
33800 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
33810 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
33820 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
33830 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
33840 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
33850 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
33860 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
33870 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
33880 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
33890 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
338a0 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76  rolls back..*/.v
338b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
338c0 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
338d0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
338e0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
338f0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
33900 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
33910 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
33920 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
33930 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
33940 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
33950 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
33960 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2970}.**.** The 
33970 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
33980 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ook() interface.
33990 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ** registers a c
339a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
339b0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
339c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
339d0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
339e0 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
339f0 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
33a00 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
33a10 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
33a20 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
33a30 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
33a40 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
33a50 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
33a60 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
33a70 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61   same .** databa
33a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33a90 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
33aa0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
33ab0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
33ac0 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
33ad0 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
33ae0 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20  en a .** row is 
33af0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
33b00 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a  d or deleted. .*
33b10 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
33b20 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
33b30 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70  back is.** a cop
33b40 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
33b50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
33b60 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
33b70 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
33b80 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67  callback .** arg
33b90 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
33ba0 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
33bb0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
33bc0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
33bd0 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  TE],.** dependin
33be0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
33bf0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
33c00 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
33c10 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68  e invoked..** Th
33c20 65 20 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20  e third and .** 
33c30 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
33c40 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
33c50 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
33c60 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
33c70 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20  e and .** table 
33c80 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
33c90 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
33ca0 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63  ..** The final c
33cb0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
33cc0 72 20 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77  r is .** the row
33cd0 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  id of the row..*
33ce0 2a 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66  * In the case of
33cf0 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
33d00 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66   is the rowid af
33d10 74 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61  ter .** the upda
33d20 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
33d30 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
33d40 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
33d50 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
33d60 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
33d70 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
33d80 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
33d90 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
33da0 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a  sequence)..**.**
33db0 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
33dc0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
33dd0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
33de0 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a  its pArg value.*
33df0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  * is returned.  
33e00 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
33e10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
33e20 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
33e30 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65  .** {F12971} The
33e40 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
33e50 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
33e60 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63  terface causes c
33e70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
33e80 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74      function F t
33e90 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
33ea0 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  h first paramete
33eb0 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  r P whenever.** 
33ec0 20 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65           a table
33ed0 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64   row is modified
33ee0 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64  , inserted, or d
33ef0 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20  eleted on.**    
33f00 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
33f10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
33f20 2a 0a 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68  *.** {F12973} Th
33f30 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
33f40 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
33f50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33f60 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
33f70 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20         of P for 
33f80 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
33f90 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  l on the same [d
33fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33fb0 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
33fc0 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74     or NULL for t
33fd0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a  he first call..*
33fe0 2a 0a 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66  *.** {F12975} If
33ff0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
34000 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b   callback F in [
34010 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
34020 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20  ook(D,F,P)].**  
34030 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20          is NULL 
34040 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
34050 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
34060 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   made..**.** {F1
34070 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20  2977} Each call 
34080 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  to [sqlite3_upda
34090 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
340a0 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20  overrides prior 
340b0 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
340c0 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e    to the same in
340d0 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73  terface on the s
340e0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
340f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
34100 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20  ** {F12979} The 
34110 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c  update hook call
34120 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
34130 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
34140 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20  l system.**     
34150 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68       tables such
34160 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
34170 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
34180 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
34190 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38  ed..**.** {F1298
341a0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
341b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75  rameter to the u
341c0 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a  pdate callback .
341d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f  **          is o
341e0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
341f0 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
34200 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54  ELETE] or [SQLIT
34210 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20  E_UPDATE],.**   
34220 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67         depending
34230 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
34240 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
34250 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65  e callback to be
34260 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
34270 7b 46 31 32 39 38 33 7d 20 54 68 65 20 74 68 69  {F12983} The thi
34280 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
34290 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
342a0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
342b0 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20  pointers.**     
342c0 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72       to zero-ter
342d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
342e0 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20  rings which are 
342f0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
34300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
34310 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
34320 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70  that is being up
34330 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39  dated...** {F129
34340 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61  85} The final ca
34350 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
34360 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66   is the rowid of
34370 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a   the row after.*
34380 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
34390 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f  hange occurs..*/
343a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
343b0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
343c0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
343d0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
343e0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
343f0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
34400 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
34410 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
34420 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20  REF:  Enable Or 
34430 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
34440 61 67 65 72 20 43 61 63 68 65 20 7b 46 31 30 33  ager Cache {F103
34450 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  30}.**.** This r
34460 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
34470 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
34480 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
34490 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
344a0 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
344b0 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
344c0 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74  en connections t
344d0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
344e0 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20  ase..** Sharing 
344f0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
34500 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
34510 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ue and disabled 
34520 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  if the argument.
34530 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  ** is false..**.
34540 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
34550 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
34560 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
34570 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
34580 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73  s. {END} This is
34590 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20   a change as of 
345a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
345b0 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f  .5.0..** In prio
345c0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
345d0 4c 69 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61  Lite, sharing wa
345e0 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20  s.** enabled or 
345f0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
34600 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
34610 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
34620 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
34630 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
34640 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
34650 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
34660 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
34670 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
34680 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
34690 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
346a0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
346b0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
346c0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
346d0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
346e0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
346f0 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
34700 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
34710 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
34720 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
34730 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
34740 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
34750 61 63 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61  ache.   When sha
34760 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
34770 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
34780 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
34790 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20  ule()] API used 
347a0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76  to register.** v
347b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69  irtual tables wi
347c0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
347d0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
347e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
347f0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
34800 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
34810 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  e was.** enabled
34820 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
34830 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
34840 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69  error code].** i
34850 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
34860 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72  wise..**.** Shar
34870 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
34880 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
34890 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
348a0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
348b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
348c0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
348d0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
348e0 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
348f0 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
34900 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
34910 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  icitly..**.** IN
34920 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a  VARIANTS:.** .**
34930 20 7b 46 31 30 33 33 31 7d 20 41 20 73 75 63 63   {F10331} A succ
34940 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
34950 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e  n of [sqlite3_en
34960 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
34970 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  e(B)].**        
34980 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72    will enable or
34990 20 64 69 73 61 62 6c 65 20 73 68 61 72 65 64 20   disable shared 
349a0 63 61 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61  cache mode for a
349b0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a  ny subsequently.
349c0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 72 65 61  **          crea
349d0 74 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ted [database co
349e0 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65  nnection] in the
349f0 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a   same process..*
34a00 2a 0a 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68  *.** {F10336} Wh
34a10 65 6e 20 73 68 61 72 65 64 20 63 61 63 68 65 20  en shared cache 
34a20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20  is enabled, the 
34a30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34a40 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  module()].**    
34a50 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
34a60 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
34a70 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  rn an error..**.
34a80 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20  ** {F10337} The 
34a90 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
34aa0 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d  shared_cache(B)]
34ab0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34ac0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
34ad0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
34ae0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
34af0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
34b00 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
34b10 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20  .**.** {F10339} 
34b20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
34b30 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
34b40 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ult..*/.int sqli
34b50 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
34b60 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
34b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
34b80 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20  Attempt To Free 
34b90 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37  Heap Memory {F17
34ba0 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  340}.**.** The s
34bb0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
34bc0 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
34bd0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
34be0 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
34bf0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
34c00 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
34c10 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
34c20 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  y.** allocations
34c30 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
34c40 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b  abase library. {
34c50 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65  END}  Memory use
34c60 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61  d.** to cache da
34c70 74 61 62 61 73 65 20 70 61 67 65 73 20 74 6f 20  tabase pages to 
34c80 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
34c90 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
34ca0 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65  e of.** non-esse
34cb0 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53  ntial memory.  S
34cc0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
34cd0 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a  emory() returns.
34ce0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
34cf0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
34d00 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67  freed, which mig
34d10 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
34d20 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61  ss.** than the a
34d30 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
34d40 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34d50 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31  S:.**.** {F17341
34d60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34d70 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29  elease_memory(N)
34d80 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ] interface atte
34d90 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  mpts to.**      
34da0 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65 73      free N bytes
34db0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
34dc0 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
34dd0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a  non-essential.**
34de0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
34df0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c   allocations hel
34e00 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
34e10 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  e library..**.**
34e20 20 7b 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73   {F16342} The [s
34e30 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
34e40 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e  emory(N)] return
34e50 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  s the number.** 
34e60 20 20 20 20 20 20 20 20 20 6f 66 20 62 79 74 65           of byte
34e70 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
34e80 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
34e90 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a   more or less.**
34ea0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 74            than t
34eb0 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
34ec0 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ted..*/.int sqli
34ed0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
34ee0 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
34ef0 43 41 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73  CAPI3REF:  Impos
34f00 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
34f10 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a  p Size {F17350}.
34f20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
34f30 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
34f40 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  t() interface.**
34f50 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
34f60 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
34f70 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
34f80 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
34f90 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20  allocated.** by 
34fa0 53 51 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e  SQLite. If an in
34fb0 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f  ternal allocatio
34fc0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20 0a  n is requested .
34fd0 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ** that would ex
34fe0 63 65 65 64 20 74 68 65 20 73 6f 66 74 20 68 65  ceed the soft he
34ff0 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
35000 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
35010 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  y()] is.** invok
35020 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
35030 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
35040 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
35050 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
35060 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a  .** is made..**.
35070 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20  ** The limit is 
35080 63 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62  called "soft", b
35090 65 63 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71  ecause if.** [sq
350a0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
350b0 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a  mory()] cannot.*
350c0 2a 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  * free sufficien
350d0 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
350e0 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
350f0 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
35100 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
35110 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
35120 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
35130 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
35140 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41  roceeds..**.** A
35150 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
35160 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
35170 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
35180 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
35190 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
351a0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
351b0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
351c0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
351d0 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
351e0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ted..** The defa
351f0 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
35200 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
35210 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
35220 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
35230 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
35240 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
35250 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42  ap limit.  .** B
35260 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68  ut if the soft h
35270 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74  eap limit cannot
35280 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65   be honored, exe
35290 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63  cution will.** c
352a0 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20  ontinue without 
352b0 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63  error or notific
352c0 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20  ation.  This is 
352d0 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73  why the limit is
352e0 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73   .** called a "s
352f0 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
35300 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
35310 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
35320 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
35330 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
35340 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
35350 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
35360 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
35370 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
35380 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
35390 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
353a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
353b0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
353c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
353d0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
353e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
353f0 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
35400 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c  threads. The val
35410 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
35420 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
35430 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
35440 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
35450 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
35460 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
35470 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20   threads. In.** 
35480 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
35490 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
354a0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
354b0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap usage 
354c0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61  for.** individua
354d0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a  l threads..**.**
354e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
354f0 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20  ** {F16351} The 
35500 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
35510 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74  ap_limit(N)] int
35520 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
35530 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20  soft limit.**   
35540 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65         of N byte
35550 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  s on the amount 
35560 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
35570 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
35580 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
35590 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
355a0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
355b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
355c0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a   at any point.**
355d0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d            in tim
355e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32  e..**.** {F16352
355f0 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
35600 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
35610 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
35620 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a  alloc()] would.*
35630 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73 65  *          cause
35640 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e   the total amoun
35650 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d  t of allocated m
35660 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20  emory to exceed 
35670 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
35680 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
35690 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
356a0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
356b0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
356c0 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74          in an at
356d0 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20  tempt to reduce 
356e0 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  the memory usage
356f0 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65   prior to procee
35700 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
35710 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79   with the memory
35720 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65   allocation atte
35730 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  mpt..**.** {F163
35740 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  53} Calls to [sq
35750 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
35760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
35770 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67  loc()] that trig
35780 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
35790 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75  attempts to redu
357a0 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20  ce memory usage 
357b0 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74  through the soft
357c0 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20   heap limit.**  
357d0 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73          mechanis
357e0 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20  m continue even 
357f0 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 74  if the attempt t
35800 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a  o reduce memory.
35810 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61 67  **          usag
35820 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66 75  e is unsuccessfu
35830 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34  l..**.** {F16354
35840 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  } A negative or 
35850 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
35860 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
35870 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35880 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
35890 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61  it(N)] means tha
358a0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
358b0 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ft.**          h
358c0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73  eap limit and [s
358d0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
358e0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
358f0 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ly be.**        
35900 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65    called when me
35910 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65  mory is complete
35920 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  ly exhausted..**
35930 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65  .** {F16355} The
35940 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
35950 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
35960 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
35970 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45  **.** {F16358} E
35980 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
35990 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
359a0 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64  imit(N)] overrid
359b0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
359c0 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62 79     values set by
359d0 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73   all prior calls
359e0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
359f0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
35a00 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
35a10 41 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 63  API3REF:  Extrac
35a20 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
35a30 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
35a40 61 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a  able {F12850}.**
35a50 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35a60 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61  .** returns meta
35a70 2d 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  -data about a sp
35a80 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
35a90 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61   a specific data
35aa0 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63  base.** table ac
35ab0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
35ac0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  he connection ha
35ad0 6e 64 6c 65 20 70 61 73 73 65 64 20 61 73 20 74  ndle passed as t
35ae0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
35af0 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a  n .** argument..
35b00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e  **.** The column
35b10 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
35b20 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
35b30 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
35b40 61 72 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a  arameters to .**
35b50 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
35b60 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
35b70 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
35b80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
35b90 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
35ba0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20   "main", "temp" 
35bb0 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
35bc0 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
35bd0 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
35be0 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
35bf0 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c  LL. If it is NUL
35c00 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
35c10 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
35c20 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
35c30 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
35c40 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
35c50 72 69 74 68 6d 20 61 73 20 74 68 65 20 64 61 74  rithm as the dat
35c60 61 62 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65  abase engine use
35c70 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65  s to .** resolve
35c80 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
35c90 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
35ca0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
35cb0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
35cc0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
35cd0 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
35ce0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a  ble and column .
35cf0 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
35d00 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
35d10 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
35d20 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
35d30 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79  rameters .** may
35d40 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
35d50 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  Meta information
35d60 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
35d70 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
35d80 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
35d90 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
35da0 20 35 74 68 20 61 6e 64 20 73 75 62 73 65 71 75   5th and subsequ
35db0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
35dc0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
35dd0 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a   Any of these .*
35de0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  * arguments may 
35df0 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  be NULL, in whic
35e00 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
35e10 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
35e20 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66   of meta .** inf
35e30 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 69 74  ormation is omit
35e40 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ted..**.** <pre>
35e50 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20  .** Parameter   
35e60 20 20 4f 75 74 70 75 74 20 54 79 70 65 20 20 20    Output Type   
35e70 20 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a     Description.*
35e80 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  * --------------
35e90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
35ea0 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74  -----.**.**   5t
35eb0 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20  h         const 
35ec0 63 68 61 72 2a 20 20 20 20 20 20 44 61 74 61 20  char*      Data 
35ed0 74 79 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20  type.**   6th   
35ee0 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72        const char
35ef0 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74  *      Name of t
35f00 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  he default colla
35f10 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a  tion sequence .*
35f20 2a 20 20 20 37 74 68 20 20 20 20 20 20 20 20 20  *   7th         
35f30 69 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20  int             
35f40 20 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c   True if the col
35f50 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
35f60 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
35f70 20 20 20 38 74 68 20 20 20 20 20 20 20 20 20 69     8th         i
35f80 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
35f90 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
35fa0 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
35fb0 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
35fc0 20 20 20 39 74 68 20 20 20 20 20 20 20 20 20 69     9th         i
35fd0 6e 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nt              
35fe0 54 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75  True if the colu
35ff0 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d  mn is AUTOINCREM
36000 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  ENT.** </pre>.**
36010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
36020 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
36030 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
36040 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
36050 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c  for the .** decl
36060 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64  aration type and
36070 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
36080 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c  nce is valid onl
36090 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  y until the next
360a0 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79   .** call to any
360b0 20 73 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63   sqlite API func
360c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tion..**.** If t
360d0 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62  he specified tab
360e0 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61  le is actually a
360f0 20 76 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65   view, then an e
36100 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
36110 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
36120 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
36130 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
36140 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
36150 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45  nd an .** INTEGE
36160 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f  R PRIMARY KEY co
36170 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
36180 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
36190 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
361a0 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ut .** parameter
361b0 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
361c0 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
361d0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66  lared column. If
361e0 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
361f0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
36200 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20  red IPK column, 
36210 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20  then the output 
36220 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
36230 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  et as .** follow
36240 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
36250 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
36260 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
36270 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
36280 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
36290 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
362a0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
362b0 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
362c0 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
362d0 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
362e0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
362f0 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
36300 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
36310 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
36320 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
36330 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
36340 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
36350 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
36360 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
36370 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
36380 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72  nd, an SQLITE er
36390 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
363a0 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
363b0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66  r message.** lef
363c0 74 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  t in the databas
363d0 65 20 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20  e handle (to be 
363e0 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
363f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
36400 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  )..**.** This AP
36410 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
36420 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
36430 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
36440 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
36450 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
36460 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f  _METADATA prepro
36470 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
36480 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
36490 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
364a0 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
364b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
364c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
364d0 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
364e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
364f0 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
36500 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
36510 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
36520 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
36530 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
36540 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
36550 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
36560 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
36570 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
36580 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
36590 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
365a0 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
365b0 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
365c0 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
365d0 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
365e0 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
365f0 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
36600 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
36610 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36620 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
36630 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
36640 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
36650 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
36660 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
36670 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
36680 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
36690 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
366a0 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
366b0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
366c0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61  e if column is a
366d0 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
366e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
366f0 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
36700 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a  ension {F12600}.
36710 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54  **.** {F12601} T
36720 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
36730 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
36740 72 66 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74  rface.** attempt
36750 73 20 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c  s to load an SQL
36760 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
36770 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
36780 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a  in the file.** z
36790 46 69 6c 65 2e 20 7b 46 31 32 36 30 32 7d 20 54  File. {F12602} T
367a0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
367b0 73 20 7a 50 72 6f 63 2e 20 7b 46 31 32 36 30 33  s zProc. {F12603
367c0 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30  } zProc may be 0
367d0 0a 2a 2a 20 69 6e 20 77 68 69 63 68 20 63 61 73  .** in which cas
367e0 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
367f0 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65  e entry point de
36800 66 61 75 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71  faults.** to "sq
36810 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
36820 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  init"..**.** {F1
36830 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65  2604} The sqlite
36840 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
36850 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  () interface sha
36860 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
36870 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
36880 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
36890 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
368a0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
368b0 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a  **.** {F12605}.*
368c0 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * If an error oc
368d0 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
368e0 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
368f0 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
36900 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
36910 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
36920 20 61 74 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c   attempt to fill
36930 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
36940 0a 2a 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67  .** error messag
36950 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e  e text stored in
36960 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36970 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36980 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e  alloc()]..** {EN
36990 44 7d 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  D}  The calling 
369a0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
369b0 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79  free this memory
369c0 0a 2a 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  .** by calling [
369d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
369e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a  .**.** {F12606}.
369f0 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** Extension loa
36a00 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
36a10 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
36a20 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
36a30 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
36a40 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
36a50 20 74 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20   this API or an 
36a60 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
36a70 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
36a80 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
36a90 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
36aa0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
36ab0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
36ac0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
36ad0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36ae0 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
36af0 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
36b00 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
36b10 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
36b20 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
36b30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36b40 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
36b50 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
36b60 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
36b70 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
36b80 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
36b90 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
36ba0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
36bb0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
36bc0 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
36bd0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
36be0 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b  ension Loading {
36bf0 46 31 32 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f  F12620}.**.** So
36c00 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
36c10 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
36c20 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
36c30 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
36c40 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
36c50 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
36c60 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
36c70 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
36c80 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
36c90 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
36ca0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
36cb0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
36cc0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  the following.**
36cd0 20 41 50 49 20 69 73 20 70 72 6f 76 69 64 65 64   API is provided
36ce0 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
36cf0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
36d00 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
36d10 6d 20 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e  m on and.** off.
36d20 20 20 7b 46 31 32 36 32 32 7d 20 49 74 20 69 73    {F12622} It is
36d30 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
36d40 20 7b 45 4e 44 7d 20 53 65 65 20 74 69 63 6b 65   {END} See ticke
36d50 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b  t #1863..**.** {
36d60 46 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65  F12621} Call the
36d70 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
36d80 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
36d90 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68   routine.** with
36da0 20 6f 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72   onoff==1 to tur
36db0 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  n extension load
36dc0 69 6e 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61  ing on.** and ca
36dd0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
36de0 3d 3d 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62  ==0 to turn it b
36df0 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b  ack off again. {
36e00 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  END}.*/.int sqli
36e10 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
36e20 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
36e30 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
36e40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36e50 45 46 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65  EF: Make Arrange
36e60 6d 65 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74  ments To Automat
36e70 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
36e80 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30  xtension {F12640
36e90 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d  }.**.** {F12641}
36ea0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   This function.*
36eb0 2a 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65  * registers an e
36ec0 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70  xtension entry p
36ed0 6f 69 6e 74 20 74 68 61 74 20 69 73 20 61 75 74  oint that is aut
36ee0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
36ef0 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61  ed.** whenever a
36f00 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
36f10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
36f20 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
36f30 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
36f40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
36f50 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  , or [sqlite3_op
36f60 65 6e 5f 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a  en_v2()]. {END}.
36f70 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63  **.** This API c
36f80 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74  an be invoked at
36f90 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70   program startup
36fa0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67   in order to reg
36fb0 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ister.** one or 
36fc0 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20  more statically 
36fd0 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e  linked extension
36fe0 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61  s that will be a
36ff0 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61  vailable.** to a
37000 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  ll new database 
37010 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  connections..**.
37020 2a 2a 20 7b 46 31 32 36 34 32 7d 20 44 75 70 6c  ** {F12642} Dupl
37030 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73  icate extensions
37040 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f   are detected so
37050 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   calling this ro
37060 75 74 69 6e 65 20 6d 75 6c 74 69 70 6c 65 0a 2a  utine multiple.*
37070 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
37080 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20   same extension 
37090 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a  is harmless..**.
370a0 2a 2a 20 7b 46 31 32 36 34 33 7d 20 54 68 69 73  ** {F12643} This
370b0 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
370c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
370d0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e   extension in an
370e0 20 61 72 72 61 79 0a 2a 2a 20 74 68 61 74 20 69   array.** that i
370f0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
37100 73 71 6c 69 74 65 5f 6d 61 6c 6c 6f 63 28 29 2e  sqlite_malloc().
37110 20 7b 45 4e 44 7d 20 49 66 20 79 6f 75 20 72 75   {END} If you ru
37120 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a  n a memory leak.
37130 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f  ** checker on yo
37140 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69  ur program and i
37150 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b  t reports a leak
37160 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   because of this
37170 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20  .** array, then 
37180 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
37190 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
371a0 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a  sion()] prior.**
371b0 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20   to shutdown to 
371c0 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e  free the memory.
371d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 34 7d 20  .**.** {F12644} 
371e0 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  Automatic extens
371f0 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73  ions apply acros
37200 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b  s all threads. {
37210 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
37220 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78 70  interface is exp
37230 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
37240 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
37250 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61 6c  ge or.** removal
37260 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
37270 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
37280 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
37290 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
372a0 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 3b  d *xEntryPoint);
372b0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
372c0 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74  F: Reset Automat
372d0 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  ic Extension Loa
372e0 64 69 6e 67 20 7b 46 31 32 36 36 30 7d 0a 2a 2a  ding {F12660}.**
372f0 0a 2a 2a 20 7b 46 31 32 36 36 31 7d 20 54 68 69  .** {F12661} Thi
37300 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
37310 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73  les all previous
37320 6c 79 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  ly registered.**
37330 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e   automatic exten
37340 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 54 68  sions. {END}  Th
37350 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  is.** routine un
37360 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
37370 6f 66 20 61 6c 6c 20 70 72 69 6f 72 20 5b 73 71  of all prior [sq
37380 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
37390 73 69 6f 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  sion()].** calls
373a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 32 7d  ..**.** {F12662}
373b0 20 54 68 69 73 20 63 61 6c 6c 20 64 69 73 61 62   This call disab
373c0 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 20 65 78  led automatic ex
373d0 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
373e0 74 68 72 65 61 64 73 2e 20 7b 45 4e 44 7d 0a 2a  threads. {END}.*
373f0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
37400 61 63 65 20 69 73 20 65 78 70 65 72 69 6d 65 6e  ace is experimen
37410 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65  tal and is subje
37420 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a  ct to change or.
37430 2a 2a 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  ** removal in fu
37440 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
37450 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64   SQLite..*/.void
37460 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
37470 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
37480 69 64 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a  id);.../*.******
37490 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20   EXPERIMENTAL - 
374a0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
374b0 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65  e without notice
374c0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a   **************.
374d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  **.** The interf
374e0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
374f0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
37500 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  sm is currently 
37510 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
37520 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
37530 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
37540 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
37550 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
37560 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
37570 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
37580 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
37590 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
375a0 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
375b0 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
375c0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
375d0 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
375e0 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
375f0 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
37600 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
37610 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
37620 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
37630 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
37640 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73  ** Structures us
37650 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61  ed by the virtua
37660 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
37670 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  e.*/.typedef str
37680 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
37690 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74   sqlite3_vtab;.t
376a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
376b0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
376c0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
376d0 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72  nfo;.typedef str
376e0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
376f0 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f  _cursor sqlite3_
37700 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70  vtab_cursor;.typ
37710 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
37720 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74  te3_module sqlit
37730 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a  e3_module;../*.*
37740 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
37750 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74  ual Table Object
37760 20 7b 46 31 38 30 30 30 7d 0a 2a 2a 20 4b 45 59   {F18000}.** KEY
37770 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
37780 6f 64 75 6c 65 0a 2a 2a 0a 2a 2a 20 41 20 6d 6f  odule.**.** A mo
37790 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20  dule is a class 
377a0 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  of virtual table
377b0 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  s.  Each module 
377c0 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  is defined.** by
377d0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
377e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
377f0 72 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73  ructure.  This s
37800 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
37810 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  s.** mostly of m
37820 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
37830 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74  odule..*/.struct
37840 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
37850 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
37860 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
37870 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
37880 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
37890 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
378a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
378b0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
378c0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
378d0 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
378e0 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
378f0 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
37900 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
37910 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37920 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
37930 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
37940 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37950 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
37960 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
37970 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
37980 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
37990 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
379a0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
379b0 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
379c0 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
379d0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
379e0 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
379f0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
37a00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
37a10 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37a20 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
37a30 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
37a40 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
37a50 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
37a60 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
37a70 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
37a80 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37a90 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
37aa0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
37ab0 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
37ac0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
37ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
37ae0 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
37af0 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
37b00 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
37b10 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
37b20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
37b30 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
37b40 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
37b50 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
37b60 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37b70 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
37b80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
37b90 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
37ba0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
37bb0 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
37bc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
37bd0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
37be0 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
37bf0 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
37c00 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
37c10 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
37c20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
37c30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37c40 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
37c50 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
37c60 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
37c70 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
37c80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37c90 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
37ca0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
37cb0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
37cc0 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
37cd0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
37ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37cf0 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
37d00 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
37d10 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
37d20 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
37d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37d40 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
37d50 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ..  int (*xRenam
37d60 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
37d70 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
37d80 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
37d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
37da0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
37db0 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
37dc0 6e 20 7b 46 31 38 31 30 30 7d 0a 2a 2a 20 4b 45  n {F18100}.** KE
37dd0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
37de0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a  index_info.**.**
37df0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
37e00 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
37e10 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
37e20 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
37e30 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
37e40 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
37e50 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
37e60 79 20 66 72 6f 6d 20 74 68 65 20 78 42 65 73 74  y from the xBest
37e70 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68 6f 64 20  Index.** method 
37e80 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 6d 6f  of an sqlite3_mo
37e90 64 75 6c 65 2e 20 20 54 68 65 20 66 69 65 6c 64  dule.  The field
37ea0 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
37eb0 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
37ec0 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
37ed0 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
37ee0 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
37ef0 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
37f00 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
37f10 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
37f20 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  elds..**.** The 
37f30 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
37f40 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52  ray records WHER
37f50 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
37f60 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  ints of the.** f
37f70 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 20 20  orm:.**.**      
37f80 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70     column OP exp
37f90 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65 20 4f 50  r.**.** Where OP
37fa0 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74   is =, &lt;, &lt
37fb0 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74  ;=, &gt;, or &gt
37fc0 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65 20 70 61 72  ;=.  .** The par
37fd0 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72  ticular operator
37fe0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
37ff0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f   aConstraint[].o
38000 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f 66  p.  The index of
38010 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
38020 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20 61 43 6f  tored in .** aCo
38030 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
38040 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74  mn.  aConstraint
38050 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55  [].usable is TRU
38060 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72  E if the.** expr
38070 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61   on the right-ha
38080 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65  nd side can be e
38090 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68  valuated (and th
380a0 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  us the constrain
380b0 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20  t.** is usable) 
380c0 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20  and false if it 
380d0 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  cannot..**.** Th
380e0 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f  e optimizer auto
380f0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74  matically invert
38100 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66  s terms of the f
38110 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c  orm "expr OP col
38120 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65  umn".** and make
38130 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69  s other simplifi
38140 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57  cations to the W
38150 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61  HERE clause in a
38160 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  n attempt to.** 
38170 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52  get as many WHER
38180 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
38190 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f  nto the form sho
381a0 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73  wn above as poss
381b0 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f  ible..** The aCo
381c0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
381d0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48   only reports WH
381e0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
381f0 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a   in the correct.
38200 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66  ** form that ref
38210 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  er to the partic
38220 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
38230 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
38240 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74  ..**.** Informat
38250 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
38260 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
38270 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
38280 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74  rBy[]..** Each t
38290 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20  erm of aOrderBy 
382a0 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e  records a column
382b0 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
382c0 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54   clause..**.** T
382d0 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
382e0 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61  thod must fill a
382f0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
38300 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  ] with informati
38310 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74  on.** about what
38320 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70   parameters to p
38330 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  ass to xFilter. 
38340 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20   If argvIndex>0 
38350 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68  then.** the righ
38360 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
38370 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
38380 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69   aConstraint[] i
38390 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61  s evaluated.** a
383a0 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61  nd becomes the a
383b0 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72  rgvIndex-th entr
383c0 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66 20 61  y in argv.  If a
383d0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
383e0 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75  ].omit.** is tru
383f0 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73  e, then the cons
38400 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65  traint is assume
38410 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61  d to be fully ha
38420 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  ndled by the.** 
38430 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
38440 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64  d is not checked
38450 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65   again by SQLite
38460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64 78 4e  ..**.** The idxN
38470 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61  um and idxPtr va
38480 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65  lues are recorde
38490 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74  d and passed int
384a0 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a 20 73 71  o xFilter..** sq
384b0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
384c0 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78  used to free idx
384d0 50 74 72 20 69 66 20 6e 65 65 64 54 6f 46 72 65  Ptr if needToFre
384e0 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e  eIdxPtr is true.
384f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72  .**.** The order
38500 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73  ByConsumed means
38510 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f   that output fro
38520 6d 20 78 46 69 6c 74 65 72 20 77 69 6c 6c 20 6f  m xFilter will o
38530 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63  ccur in.** the c
38540 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20  orrect order to 
38550 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45  satisfy the ORDE
38560 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74  R BY clause so t
38570 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a  hat no separate.
38580 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20  ** sorting step 
38590 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
385a0 2a 2a 20 54 68 65 20 65 73 74 69 6d 61 74 65 64  ** The estimated
385b0 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e  Cost value is an
385c0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65   estimate of the
385d0 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74   cost of doing t
385e0 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72  he.** particular
385f0 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c   lookup.  A full
38600 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65   scan of a table
38610 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20   with N entries 
38620 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61  should have.** a
38630 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62   cost of N.  A b
38640 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20  inary search of 
38650 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74  a table of N ent
38660 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
38670 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70   a.** cost of ap
38680 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28  proximately log(
38690 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  N)..*/.struct sq
386a0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
386b0 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a   {.  /* Inputs *
386c0 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61  /.  int nConstra
386d0 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f  int;           /
386e0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72  * Number of entr
386f0 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  ies in aConstrai
38700 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  nt */.  struct s
38710 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
38720 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69  straint {.     i
38730 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
38740 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
38750 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20  mn on left-hand 
38760 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69  side of constrai
38770 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  nt */.     unsig
38780 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20  ned char op;    
38790 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69       /* Constrai
387a0 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20  nt operator */. 
387b0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
387c0 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a  r usable;     /*
387d0 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f   True if this co
387e0 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62  nstraint is usab
387f0 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69  le */.     int i
38800 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20  TermOffset;     
38810 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74       /* Used int
38820 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49  ernally - xBestI
38830 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f  ndex should igno
38840 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  re */.  } *aCons
38850 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
38860 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57     /* Table of W
38870 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
38880 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74  traints */.  int
38890 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
388a0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
388b0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68  r of terms in th
388c0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
388d0 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  e */.  struct sq
388e0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
388f0 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  rby {.     int i
38900 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
38910 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e       /* Column n
38920 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e  umber */.     un
38930 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
38940 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
38950 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65  for DESC.  False
38960 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d   for ASC. */.  }
38970 20 2a 61 4f 72 64 65 72 42 79 3b 20