/ Hex Artifact Content
Login

Artifact 44a3ab74e6677490133ea5efd4ee649dedcf9048:


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 33 35 20 32 30 30 38 2f  in,v 1.335 2008/
05f0: 30 36 2f 31 38 20 31 38 3a 31 32 3a 30 34 20 64  06/18 18:12:04 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 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
8c70: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
8c80: 6c 69 62 72 61 72 79 20 70 72 69 6f 72 20 74 6f  library prior to
8c90: 20 75 73 65 2e 20 20 54 68 65 20 73 71 6c 69 74   use.  The sqlit
8ca0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
8cb0: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
8cc0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
8cd0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
8ce0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
8cf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
8d00: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
8d10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8d20: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
8d30: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
8d40: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
8d50: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
8d60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
8d70: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
8d80: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
8d90: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
8da0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
8db0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
8dc0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
8dd0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
8de0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
8df0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8e00: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66  ().  Only an eff
8e10: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
8e20: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
8e30: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
8e40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
8e50: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
8e60: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
8e70: 20 6e 6f 2d 6f 70 73 2e 20 20 49 6e 20 6f 74 68   no-ops.  In oth
8e80: 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
8e90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8ea0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 6d 61  ize() routine ma
8eb0: 79 20 62 65 20 63 61 6c 6c 65 64 20 6d 75 6c 74  y be called mult
8ec0: 69 70 6c 65 20 74 69 6d 65 73 0a 2a 2a 20 77 69  iple times.** wi
8ed0: 74 68 6f 75 74 20 63 6f 6e 73 65 71 75 65 6e 63  thout consequenc
8ee0: 65 2e 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73  e.  Second and s
8ef0: 75 62 73 65 71 75 65 6e 74 20 65 76 61 6c 75 61  ubsequent evalua
8f00: 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 73 71 6c 69  tions of.** sqli
8f10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8f20: 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 20 20 54 68   are no-ops.  Th
8f30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
8f40: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 0a 2a  lize() routine.*
8f50: 2a 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 74 68 65  * only works the
8f60: 20 66 69 72 73 74 20 74 69 6d 65 20 69 74 20 69   first time it i
8f70: 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20 70  s called for a p
8f80: 72 6f 63 65 73 73 2c 20 6f 72 20 74 68 65 20 66  rocess, or the f
8f90: 69 72 73 74 0a 2a 2a 20 74 69 6d 65 20 69 74 20  irst.** time it 
8fa0: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
8fb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
8fc0: 28 29 2e 20 20 49 6e 20 61 6c 6c 20 6f 74 68 65  ().  In all othe
8fd0: 72 20 63 61 73 65 73 2c 0a 2a 2a 20 73 71 6c 69  r cases,.** sqli
8fe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8ff0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9000: 4f 4b 20 77 69 74 68 6f 75 74 20 64 6f 69 6e 67  OK without doing
9010: 20 61 6e 79 20 72 65 61 6c 20 77 6f 72 6b 2e 0a   any real work..
9020: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
9030: 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65  r things, sqlite
9040: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
9050: 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b  hall invoke.** [
9060: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 69 6e  sqlite3_mutex_in
9070: 69 74 28 29 5d 20 61 6e 64 20 73 71 6c 69 74 65  it()] and sqlite
9080: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
9090: 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33  milarly, sqlite3
90a0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73  _shutdown().** s
90b0: 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  hall invoke [sql
90c0: 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 64 28 29  ite3_mutex_end()
90d0: 5d 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ] and sqlite3_os
90e0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  _end()..**.** Th
90f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9100: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9110: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
9120: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
9130: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
9140: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
9150: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
9160: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
9170: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
9180: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
9190: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
91a0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
91b0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
91c0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
91d0: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
91e0: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51  e] other than SQ
91f0: 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54  LITE_OK..**.** T
9200: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9210: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9220: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
9230: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
9240: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
9250: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
9260: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
9270: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
9280: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
9290: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
92a0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
92b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
92c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
92d0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
92e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
92f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
9300: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
9310: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
9320: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
9330: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
9340: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
9350: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
9360: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
9370: 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  .  However, if S
9380: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9390: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
93a0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a  E_OMIT_AUTOINIT.
93b0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
93c0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
93d0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
93e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
93f0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
9400: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
9410: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
9420: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
9430: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9440: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
9450: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
9460: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9470: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
9480: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
9490: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
94a0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
94b0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
94c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
94d0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
94e0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
94f0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
9500: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
9510: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
9520: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
9530: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
9540: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
9550: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
9560: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
9570: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9580: 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54  with SQLITE_OMIT
9590: 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20  _AUTOINIT might 
95a0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
95b0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
95c0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
95d0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
95e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
95f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
9600: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
9610: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
9620: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
9630: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
9640: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
9650: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
9660: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
9670: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
9680: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
9690: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
96a0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
96b0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
96c0: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
96d0: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
96e0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
96f0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
9700: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
9710: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
9720: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
9730: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
9740: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
9750: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
9760: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
9770: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
9780: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
9790: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].  .**.** The 
97a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
97b0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
97c0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
97d0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
97e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
97f0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
9800: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9810: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
9820: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9830: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
9840: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
9850: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
9860: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
9870: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
9880: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
9890: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
98a0: 29 20 61 6e 64 20 0a 2a 2a 20 73 71 6c 69 74 65  ) and .** sqlite
98b0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
98c0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
98d0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
98e0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
98f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
9900: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9910: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
9920: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
9930: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
9940: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
9950: 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69  led for unix, wi
9960: 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a  ndows, or os/2..
9970: 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f  ** When built fo
9980: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
9990: 73 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c  s (using the SQL
99a0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63  ITE_OS_OTHER=1 c
99b0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
99c0: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
99d0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
99e0: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
99f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
9a00: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
9a10: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
9a20: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
9a30: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
9a40: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
9a50: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
9a60: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
9a70: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
9a80: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53  ** must return S
9a90: 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63  QLITE_OK on succ
9aa0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
9ab0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
9ac0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
9ad0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
9ae0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
9af0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
9b00: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
9b10: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
9b20: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
9b30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
9b40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
9b50: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
9b60: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
9b70: 72 79 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a  ry {F10145}.**.*
9b80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
9b90: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
9ba0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
9bb0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
9bc0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
9bd0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
9be0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
9bf0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
9c00: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
9c10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
9c20: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
9c30: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
9c40: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
9c50: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
9c60: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
9c70: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
9c80: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
9c90: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
9ca0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
9cb0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
9cc0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
9cd0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
9ce0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
9cf0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
9d00: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
9d10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
9d20: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
9d30: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
9d40: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
9d50: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
9d60: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
9d70: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
9d80: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
9d90: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
9da0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
9db0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
9dc0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
9dd0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
9de0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
9df0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9e00: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
9e10: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
9e20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
9e30: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
9e40: 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  r, that sqlite3_
9e50: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
9e60: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
9e70: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
9e80: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
9e90: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
9ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
9eb0: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
9ec0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
9ed0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
9ee0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
9ef0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
9f00: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
9f10: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
9f20: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
9f30: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
9f40: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
9f50: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
9f60: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
9f70: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
9f80: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
9f90: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
9fa0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
9fb0: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
9fc0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
9fd0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
9fe0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
9ff0: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
a000: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
a010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a020: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
a030: 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  OK..** If the op
a040: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
a050: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
a060: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
a070: 70 74 69 6f 6e 20 0a 2a 2a 20 74 68 65 6e 20 74  ption .** then t
a080: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
a090: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
a0a0: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
a0b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
a0c0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
a0d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
a0e0: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
a0f0: 20 52 6f 75 74 69 6e 65 73 20 7b 46 31 30 31 35   Routines {F1015
a100: 35 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  5}.**.** An inst
a110: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a120: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
a130: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
a140: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
a150: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
a160: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
a170: 69 6e 65 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  ines.  .**.** Th
a180: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
a190: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
a1a0: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
a1b0: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
a1c0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
a1d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
a1e0: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
a1f0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
a200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 20 77  qlite3_config] w
a210: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
a220: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
a230: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
a240: 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63  G_MALLOC].  By c
a250: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
a260: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
a270: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
a280: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
a290: 5f 63 6f 6e 66 69 67 5d 20 64 75 72 69 6e 67 20  _config] during 
a2a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
a2b0: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
a2c0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
a2d0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
a2e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
a2f0: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53  bsystem.** for S
a300: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
a310: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
a320: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
a330: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
a340: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
a350: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d  ith a built-in m
a360: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
a370: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65  that is.** perfe
a380: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
a390: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
a3a0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
a3b0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
a3c0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
a3d0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
a3e0: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
a3f0: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
a400: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
a410: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
a420: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
a430: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
a440: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
a450: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
a460: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
a470: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
a480: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
a490: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
a4a0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
a4b0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
a4c0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
a4d0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
a4e0: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
a4f0: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
a500: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
a510: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
a520: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
a530: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61  Malloc, xFree, a
a540: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  nd xRealloc meth
a550: 6f 64 73 20 73 68 6f 75 6c 64 20 77 6f 72 6b 20  ods should work 
a560: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
a570: 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e  oc(), free(), an
a580: 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63  d realloc() func
a590: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
a5a0: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e  tandard library.
a5b0: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
a5c0: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
a5d0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
a5e0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
a5f0: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
a600: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
a610: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
a620: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
a630: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
a640: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
a650: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
a660: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
a670: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
a680: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
a690: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
a6a0: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
a6b0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
a6c0: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
a6d0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
a6e0: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
a6f0: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
a700: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
a710: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
a720: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
a730: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
a740: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
a750: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
a760: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
a770: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
a780: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
a790: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
a7a0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69   .**.** The xIni
a7b0: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
a7c0: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
a7d0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
a7e0: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
a7f0: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
a800: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
a810: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
a820: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
a830: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
a840: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
a850: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
a860: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
a870: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
a880: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
a890: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
a8a0: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
a8b0: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
a8c0: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
a8d0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
a8e0: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
a8f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
a900: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
a910: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a920: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a930: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
a940: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
a950: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
a960: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
a970: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
a980: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
a990: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
a9a0: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
a9b0: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
a9c0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
a9d0: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
a9e0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
a9f0: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
aa00: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
aa10: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
aa20: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
aa30: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
aa40: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
aa50: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
aa60: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
aa70: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
aa80: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
aa90: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
aaa0: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
aab0: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
aac0: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
aad0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
aae0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
aaf0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ab00: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
ab10: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
ab20: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
ab30: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
ab40: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
ab50: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
ab60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
ab70: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
ab80: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
ab90: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
aba0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
abb0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
abc0: 73 20 7b 46 31 30 31 36 30 7d 0a 2a 2a 0a 2a 2a  s {F10160}.**.**
abd0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
abe0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
abf0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
ac00: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
ac10: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
ac20: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
ac30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ac40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
ac50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ac60: 2e 0a 2a 2a 20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ..** .** <dl>.**
ac70: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ac80: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
ac90: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
aca0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
acb0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
acc0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
acd0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
ace0: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
acf0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
ad00: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
ad10: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
ad20: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
ad30: 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  read.</dd>.**.**
ad40: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ad50: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
ad60: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
ad70: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
ad80: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
ad90: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 64  .  This option d
ada0: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
adb0: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
adc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
add0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
ade0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
adf0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
ae00: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
ae10: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
ae20: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
ae30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ae40: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
ae50: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
ae60: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
ae70: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
ae80: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
ae90: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
aea0: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
aeb0: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
aec0: 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  ronment.</dd>.**
aed0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
aee0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
aef0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
af00: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
af10: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
af20: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
af30: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
af40: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
af50: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
af60: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
af70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
af80: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
af90: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
afa0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
afb0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
afc0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
afd0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
afe0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
aff0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 29  TE_THREADSAFE=1)
b000: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
b010: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
b020: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
b030: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
b040: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
b050: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b060: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
b070: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
b080: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
b090: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
b0a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
b0b0: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
b0c0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
b0d0: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
b0e0: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
b0f0: 20 73 61 6d 65 20 74 69 6d 65 2e 3c 2f 64 64 3e   same time.</dd>
b100: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
b110: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
b120: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b130: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
b140: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
b150: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
b160: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
b170: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
b180: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b190: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
b1a0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
b1b0: 66 69 63 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fics.** alternat
b1c0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
b1d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b1e0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
b1f0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
b200: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b210: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
b220: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
b230: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b240: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
b250: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
b260: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b270: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
b280: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
b290: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b2a0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
b2b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
b2c0: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
b2d0: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
b2e0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
b2f0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
b300: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b310: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
b320: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
b330: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
b340: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
b350: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
b360: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
b370: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
b380: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
b390: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
b3a0: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
b3b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b3c0: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
b3d0: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
b3e0: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
b3f0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b400: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
b410: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
b420: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b430: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f   takes single bo
b440: 6f 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77  olean argument w
b450: 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
b460: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20  disables.** the 
b470: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
b480: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b490: 73 74 61 74 69 73 74 69 63 73 2e 20 20 57 68 65  statistics.  Whe
b4a0: 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a  n disabled, the.
b4b0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
b4c0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
b4d0: 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
b4e0: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
b4f0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
b500: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
b510: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
b520: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
b530: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
b540: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
b550: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a  t_heap_limit()].
b560: 2a 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65  **   <li> sqlite
b570: 33 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28  3_memory_status(
b580: 29 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20  ).**   </ul>.** 
b590: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b5a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
b5b0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
b5c0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
b5d0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
b5e0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
b5f0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
b600: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
b610: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
b620: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
b630: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
b640: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
b650: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
b660: 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66  ach scratch buff
b670: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
b680: 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65   number of buffe
b690: 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  rs (N).  The sz.
b6a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
b6b0: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
b6c0: 66 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a  f 16. The first.
b6d0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
b6e0: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
b6f0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
b700: 6c 65 61 73 74 20 28 73 7a 2b 31 29 2a 4e 20 62  least (sz+1)*N b
b710: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
b720: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
b730: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
b740: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
b750: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
b760: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
b770: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
b780: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
b790: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
b7a0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 20  hreads.  The sz 
b7b0: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68  .** parameter sh
b7c0: 6f 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20  ould be 6 times 
b7d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b7e0: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
b7f0: 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53   page size..** S
b800: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61  cratch buffers a
b810: 72 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20  re used as part 
b820: 6f 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c  of the btree bal
b830: 61 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  ance operation. 
b840: 20 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65   If.** The btree
b850: 20 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20   balancer needs 
b860: 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  additional memor
b870: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
b880: 20 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20   provided by.** 
b890: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
b8a0: 6f 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68  or if no scratch
b8b0: 20 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73   buffer space is
b8c0: 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
b8d0: 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20   SQLite.** goes 
b8e0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
b8f0: 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20  oc()] to obtain 
b900: 74 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65  the memory it ne
b910: 65 64 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  eds..** </dd>.**
b920: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
b930: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
b940: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
b950: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
b960: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
b970: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
b980: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
b990: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
b9a0: 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 68   page cache.  Th
b9b0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
b9c0: 67 75 6d 65 6e 74 73 3a 0a 2a 2a 20 41 20 70 6f  guments:.** A po
b9d0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
b9e0: 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65  ory, the.** size
b9f0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
ba00: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
ba10: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
ba20: 65 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  es (N).  The sz.
ba30: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
ba40: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
ba50: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
ba60: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
ba70: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
ba80: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
ba90: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
baa0: 66 20 61 74 20 6c 65 61 73 74 20 28 73 7a 2b 34  f at least (sz+4
bab0: 29 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  )*N bytes of mem
bac0: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
bad0: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
bae0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
baf0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bb00: 74 20 74 6f 20 73 61 74 69 73 66 79 0a 2a 2a 20  t to satisfy.** 
bb10: 69 74 73 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  its memory needs
bb20: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
bb30: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
bb40: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49  dds to cache.  I
bb50: 66 20 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  f .** additional
bb60: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
bb70: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
bb80: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
bb90: 69 64 65 64 20 62 79 0a 2a 2a 20 74 68 69 73 20  ided by.** this 
bba0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  option, then SQL
bbb0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
bbc0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
bbd0: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
bbe0: 6c 0a 2a 2a 20 73 74 6f 72 61 67 65 20 73 70 61  l.** storage spa
bbf0: 63 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ce..** </dd>.**.
bc00: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bc10: 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
bc20: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
bc30: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
bc40: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
bc50: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
bc60: 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
bc70: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
bc80: 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
bc90: 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
bca0: 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
bcb0: 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
bcc0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
bcd0: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
bce0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
bcf0: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
bd00: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
bd10: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
bd20: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62  memory, the numb
bd30: 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
bd40: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
bd50: 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
bd60: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
bd70: 73 69 7a 65 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  size.  When.** t
bd80: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
bd90: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  n option is used
bda0: 2c 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 63  , SQLite never c
bdb0: 61 6c 6c 73 20 74 68 65 20 73 79 73 74 65 6d 0a  alls the system.
bdc0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  ** malloc() impl
bdd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 62 75 74 20 69  ementation but i
bde0: 6e 73 74 65 61 64 20 75 73 65 73 20 74 68 65 20  nstead uses the 
bdf0: 73 75 70 70 6c 69 65 64 20 6d 65 6d 6f 72 79 20  supplied memory 
be00: 62 75 66 66 65 72 0a 2a 2a 20 74 6f 20 73 61 74  buffer.** to sat
be10: 69 73 66 79 20 61 6c 6c 20 5b 73 71 6c 69 74 65  isfy all [sqlite
be20: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 72 65 71 75  3_malloc()] requ
be30: 65 73 74 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ests..** </dd>.*
be40: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
be50: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
be60: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
be70: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
be80: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
be90: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
bea0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
beb0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
bec0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
bed0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
bee0: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
bef0: 69 63 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ics.** alternati
bf00: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
bf10: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
bf20: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
bf30: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
bf40: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
bf50: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
bf60: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bf70: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
bf80: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bf90: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bfa0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bfb0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bfc0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
bfd0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
bfe0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
bff0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c000: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
c010: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
c020: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
c030: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
c040: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
c050: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
c060: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
c070: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
c080: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
c090: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
c0a0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
c0b0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
c0c0: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
c0d0: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
c0e0: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
c0f0: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
c100: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  g, for example.<
c110: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
c120: 0a 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c  .*/ .#define SQL
c130: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
c140: 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
c150: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
c160: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
c170: 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
c180: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
c190: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
c1a0: 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
c1b0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
c1c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c1d0: 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
c1e0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
c1f0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
c200: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c210: 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
c220: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
c230: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
c240: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c250: 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
c260: 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
c270: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
c280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c290: 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
c2a0: 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
c2b0: 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
c2c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c2d0: 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
c2e0: 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
c2f0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
c300: 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
c310: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
c320: 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
c330: 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
c340: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c350: 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
c360: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
c370: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
c380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c390: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
c3a0: 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
c3b0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
c3c0: 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
c3d0: 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
c3e0: 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
c3f0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46   Result Codes {F
c400: 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12200}.**.** The
c410: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
c420: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
c430: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
c440: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
c450: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
c460: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
c470: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
c480: 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
c490: 65 2e 0a 2a 2a 20 54 68 65 20 65 78 74 65 6e 64  e..** The extend
c4a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
c4b0: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
c4c0: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
c4d0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
c4e0: 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49  ibility..**.** I
c4f0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
c500: 20 7b 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e   {F12201} Each n
c510: 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
c520: 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68  nection] shall h
c530: 61 76 65 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ave the .**     
c540: 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72       [extended r
c550: 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
c560: 74 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ture.**         
c570: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
c580: 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ault..**.** {F12
c590: 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  202} The [sqlite
c5a0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
c5b0: 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e  t_codes(D,F)] in
c5c0: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e  terface shall en
c5d0: 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
c5e0: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
c5f0: 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65  t codes] for the
c600: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64   .**          [d
c610: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c620: 6f 6e 5d 20 44 20 69 66 20 74 68 65 20 46 20 70  on] D if the F p
c630: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
c640: 20 20 20 20 20 69 73 20 74 72 75 65 2c 20 6f 72       is true, or
c650: 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66   disable them if
c660: 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a   F is false..*/.
c670: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
c680: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
c690: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
c6a0: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
c6b0: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
c6c0: 73 65 72 74 20 52 6f 77 69 64 20 7b 46 31 32 32  sert Rowid {F122
c6d0: 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65  20}.**.** Each e
c6e0: 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
c6f0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
c700: 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
c710: 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
c720: 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f  y called the "ro
c730: 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20  wid". The rowid 
c740: 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
c750: 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
c760: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
c770: 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
c780: 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
c790: 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
c7a0: 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
c7b0: 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
c7c0: 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
c7d0: 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68  olumns. If.** th
c7e0: 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
c7f0: 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54  lumn of type INT
c800: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
c810: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
c820: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
c830: 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
c840: 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  wid..**.** This 
c850: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
c860: 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
c870: 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
c880: 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52  successful INSER
c890: 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  T into the datab
c8a0: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61 74  ase from the dat
c8b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c8c0: 0a 2a 2a 20 73 68 6f 77 6e 20 69 6e 20 74 68 65  .** shown in the
c8d0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
c8e0: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
c8f0: 75 6c 20 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61  ul inserts.** ha
c900: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
c910: 20 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73   on this databas
c920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
c930: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
c940: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45  **.** If an INSE
c950: 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  RT occurs within
c960: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
c970: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
c980: 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20 72 6f  e.** inserted ro
c990: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
c9a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
c9b0: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
c9c0: 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  gger.** is runni
c9d0: 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20 74 68  ng.  But once th
c9e0: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
c9f0: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
ca00: 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74  returned.** by t
ca10: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
ca20: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
ca30: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
ca40: 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74 72 69  efore the.** tri
ca50: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
ca60: 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74  * An INSERT that
ca70: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
ca80: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
ca90: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
caa0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65   successful inse
cab0: 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  rt and does not 
cac0: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
cad0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
cae0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
caf0: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
cb00: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
cb10: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
cb20: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
cb30: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
cb40: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
cb50: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
cb60: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
cb70: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
cb80: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
cb90: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
cba0: 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20   OR REPLACE .** 
cbb0: 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
cbc0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
cbd0: 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
cbe0: 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
cbf0: 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
cc00: 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
cc10: 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
cc20: 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
cc30: 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
cc40: 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
cc50: 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
cc60: 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
cc70: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
cc80: 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
cc90: 61 63 65 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ace. .**.** For 
cca0: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
ccb0: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
ccc0: 20 69 6e 73 65 72 74 20 69 73 20 63 6f 6e 73 69   insert is consi
ccd0: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
cce0: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
ccf0: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
cd00: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
cd10: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
cd20: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32  TS:.**.** {F1222
cd30: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
cd40: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
cd50: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
cd60: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
cd70: 20 20 20 20 20 20 72 6f 77 69 64 20 6f 66 20 74        rowid of t
cd80: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
cd90: 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74  uccessful insert
cda0: 20 64 6f 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20   done.**        
cdb0: 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61    on the same da
cdc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cdd0: 6e 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65  n and within the
cde0: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
cdf0: 20 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65    or higher leve
ce00: 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  l trigger contex
ce10: 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68  t, or zero if th
ce20: 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20  ere have.**     
ce30: 20 20 20 20 20 62 65 65 6e 20 6e 6f 20 71 75 61       been no qua
ce40: 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e  lifying inserts.
ce50: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20  .**.** {F12223} 
ce60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
ce70: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
ce80: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
ce90: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ns.**          s
cea0: 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63  ame value when c
ceb0: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
cec0: 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74  ame trigger cont
ced0: 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
cee0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
cef0: 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52  re and after a R
cf00: 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c  OLLBACK..**.** L
cf10: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
cf20: 2a 20 7b 55 31 32 32 33 32 7d 20 49 66 20 61 20  * {U12232} If a 
cf30: 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
cf40: 64 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72  does a new inser
cf50: 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  t on the same.**
cf60: 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
cf70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
cf80: 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
cf90: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
cfa0: 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  id()].**        
cfb0: 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75    function is ru
cfc0: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
cfd0: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
cfe0: 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a  insert rowid,.**
cff0: 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
d000: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d010: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
d020: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
d030: 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
d040: 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
d050: 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
d060: 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
d070: 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
d080: 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
d090: 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a  nsert rowid..*/.
d0a0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
d0b0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
d0c0: 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
d0d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
d0e0: 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
d0f0: 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
d100: 69 66 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a  ified {F12240}.*
d110: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
d120: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
d130: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
d140: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
d150: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
d160: 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
d170: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
d180: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
d190: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
d1a0: 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63  ** on the connec
d1b0: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
d1c0: 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
d1d0: 6d 65 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  meter.  Only.** 
d1e0: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
d1f0: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
d200: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
d210: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a  T, UPDATE, or.**
d220: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
d230: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
d240: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
d250: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
d260: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
d270: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65  counted. Use the
d280: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
d290: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
d2a0: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  ion.** to find t
d2b0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
d2c0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75  of changes inclu
d2d0: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
d2e0: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e  sed by triggers.
d2f0: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68  .**.** A "row ch
d300: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
d310: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
d320: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
d330: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
d340: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
d350: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
d360: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
d370: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
d380: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
d390: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  ts of REPLACE co
d3a0: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
d3b0: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
d3c0: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
d3d0: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20  ng, DROP TABLE, 
d3e0: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
d3f0: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
d400: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
d410: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
d420: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
d430: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
d440: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
d450: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
d460: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
d470: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
d480: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20   trigger.  Most 
d490: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
d4a0: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
d4b0: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
d4c0: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
d4d0: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
d4e0: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
d4f0: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
d500: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
d510: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
d520: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
d530: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
d540: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
d550: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
d560: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
d570: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
d580: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
d590: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
d5a0: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** Calling [sql
d5b0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
d5c0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
d5d0: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
d5e0: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
d5f0: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
d600: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ntext..**.** Thi
d610: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
d620: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
d630: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
d640: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
d650: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
d660: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
d670: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
d680: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
d690: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
d6a0: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e 20  ..**.** So when 
d6b0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
d6c0: 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
d6d0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
d6e0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
d6f0: 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
d700: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
d710: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
d720: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
d730: 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
d740: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a  the top level..*
d750: 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  * Within the bod
d760: 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20  y of a trigger, 
d770: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
d780: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ges() interface.
d790: 2a 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ** can be called
d7a0: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
d7b0: 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
d7c0: 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
d7d0: 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
d7e0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
d7f0: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
d800: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
d810: 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
d820: 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
d830: 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
d840: 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
d850: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69 6e  s not include in
d860: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
d870: 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
d880: 73 20 73 69 6e 63 65 20 74 68 65 79 20 68 61 76  s since they hav
d890: 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
d8a0: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ext..**.** SQLit
d8b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
d8c0: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
d8d0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
d8e0: 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20  hout.** a WHERE 
d8f0: 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69  clause by droppi
d900: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
d910: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
d920: 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66  his is much.** f
d930: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
d940: 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
d950: 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
d960: 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
d970: 68 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42  he.** table.)  B
d980: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f  ecause of this o
d990: 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
d9a0: 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a   deletions in.**
d9b0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
d9c0: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
d9d0: 20 63 68 61 6e 67 65 73 20 61 6e 64 20 77 69 6c   changes and wil
d9e0: 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  l not be counted
d9f0: 0a 2a 2a 20 62 79 20 74 68 65 20 73 71 6c 69 74  .** by the sqlit
da00: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
da10: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
da20: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
da30: 6f 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20 61  ons..** To get a
da40: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
da50: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
da60: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
da70: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
da80: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
da90: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
daa0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
dab0: 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65  .** {F12241} The
dac0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
dad0: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  s()] function sh
dae0: 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  all return the n
daf0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
db00: 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73       row changes
db10: 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d   caused by the m
db20: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
db30: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20  T, UPDATE,.**   
db40: 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45         or DELETE
db50: 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
db60: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
db70: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a  connection and.*
db80: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69  *          withi
db90: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
dba0: 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e  gher trigger con
dbb0: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
dbc0: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
dbd0: 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
dbe0: 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
dbf0: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
dc00: 2a 2a 20 7b 46 31 32 32 34 33 7d 20 53 74 61 74  ** {F12243} Stat
dc10: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
dc20: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
dc30: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
dc40: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
dc50: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
dc60: 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65  l cause subseque
dc70: 6e 74 20 63 61 6c 6c 73 20 74 6f 20 0a 2a 2a 20  nt calls to .** 
dc80: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
dc90: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20  3_changes()] to 
dca0: 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67  return zero, reg
dcb0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a  ardless of the.*
dcc0: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
dcd0: 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e  r of rows origin
dce0: 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c  ally in the tabl
dcf0: 65 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  e..**.** LIMITAT
dd00: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
dd10: 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  252} If a separa
dd20: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
dd30: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
dd40: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
dd50: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
dd60: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
dd70: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
dd80: 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
dd90: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
dda0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
ddb0: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
ddc0: 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
ddd0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
dde0: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
ddf0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
de00: 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
de10: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
de20: 65 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 2a 0a  ed {F12260}.***.
de30: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
de40: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
de50: 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
de60: 65 73 20 63 61 75 73 65 64 0a 2a 2a 20 62 79 20  es caused.** by 
de70: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
de80: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
de90: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 64 61  nts since the da
dea0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 0a 2a 2a  tabase handle.**
deb0: 20 77 61 73 20 6f 70 65 6e 65 64 2e 20 20 54 68   was opened.  Th
dec0: 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73  e count includes
ded0: 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f   all changes fro
dee0: 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 0a 2a 2a  m all trigger.**
def0: 20 63 6f 6e 74 65 78 74 73 2e 20 20 42 75 74 20   contexts.  But 
df00: 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
df10: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
df20: 65 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 69 6d  es used to.** im
df30: 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20  plement REPLACE 
df40: 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 64 6f 20  constraints, do 
df50: 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
df60: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 0a 2a  RT processing,.*
df70: 2a 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20  * or DROP table 
df80: 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54  processing..** T
df90: 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 61 72  he changes.** ar
dfa0: 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
dfb0: 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  n as the stateme
dfc0: 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
dfd0: 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
dfe0: 0a 2a 2a 20 28 77 68 65 6e 20 74 68 65 20 73 74  .** (when the st
dff0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69  atement handle i
e000: 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
e010: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
e020: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69   .** [sqlite3_fi
e030: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
e040: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
e050: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
e060: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e070: 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61  le" without.** a
e080: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 62 79   WHERE clause by
e090: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
e0a0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
e0b0: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
e0c0: 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61  ch.** faster tha
e0d0: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
e0e0: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
e0f0: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
e100: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
e110: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
e120: 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a  .** this optimiz
e130: 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67  ation, the chang
e140: 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c  e count for "DEL
e150: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
e160: 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20  will be.** zero 
e170: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
e180: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
e190: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
e1a0: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
e1b0: 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65  .** table. To ge
e1c0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
e1d0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
e1e0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
e1f0: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
e200: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
e210: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
e220: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
e230: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
e240: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
e250: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
e260: 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 32 36  S:.** .** {F1226
e270: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
e280: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
e290: 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
e2a0: 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  al number.**    
e2b0: 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61        of row cha
e2c0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49  nges caused by I
e2d0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61  NSERT, UPDATE, a
e2e0: 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  nd/or DELETE.** 
e2f0: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
e300: 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  nts on the same 
e310: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e320: 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a  tion], in any.**
e330: 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65            trigge
e340: 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65  r context, since
e350: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
e360: 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a 2a 20  nnection was.** 
e370: 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64           created
e380: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 33 7d  ..**.** {F12263}
e390: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
e3a0: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
e3b0: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
e3c0: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
e3d0: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
e3e0: 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67   shall not chang
e3f0: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
e400: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
e410: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   by [sqlite3_tot
e420: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
e430: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
e440: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20  .**.** {U12264} 
e450: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
e460: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
e470: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
e480: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e490: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
e4a0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
e4b0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
e4c0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
e4d0: 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 20 20 20  he value .**    
e4e0: 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69        returned i
e4f0: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
e500: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
e510: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
e520: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e530: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
e540: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
e550: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
e560: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32  nning Query {F12
e570: 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  270}.**.** This 
e580: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
e590: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
e5a0: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
e5b0: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
e5c0: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
e5d0: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
e5e0: 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
e5f0: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
e600: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
e610: 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
e620: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
e630: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
e640: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
e650: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
e660: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
e670: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
e680: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
e690: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20  *.** It is safe 
e6a0: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
e6b0: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
e6c0: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
e6d0: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
e6e0: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
e6f0: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
e700: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
e710: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
e720: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
e730: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
e740: 74 68 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  th a database co
e750: 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 0a 2a 2a  nnection that.**
e760: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
e770: 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
e780: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
e790: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
e7a0: 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 69 73  .** If an SQL is
e7b0: 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
e7c0: 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
e7d0: 65 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  e when sqlite3_i
e7e0: 6e 74 65 72 72 75 70 74 28 29 0a 2a 2a 20 69 73  nterrupt().** is
e7f0: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
e800: 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
e810: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 20 74  an opportunity t
e820: 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
e830: 2e 0a 2a 2a 20 49 74 20 6d 69 67 68 74 20 63 6f  ..** It might co
e840: 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
e850: 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20 53 51 4c 20  tion..** An SQL 
e860: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
e870: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
e880: 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
e890: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
e8a0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75    If the interru
e8b0: 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
e8c0: 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20 49 4e 53 45  on is an.** INSE
e8d0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
e8e0: 45 4c 45 54 45 20 74 68 61 74 20 69 73 20 69 6e  ELETE that is in
e8f0: 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
e900: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 0a 2a   transaction, .*
e910: 2a 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  * then the entir
e920: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 69  e transaction wi
e930: 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
e940: 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
e950: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
e960: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
e970: 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  ) has no effect 
e980: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
e990: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
e9a0: 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  arted after sqli
e9b0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
e9c0: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
e9d0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
e9e0: 20 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73   {F12271} The [s
e9f0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ea00: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
ea10: 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e  ll force all run
ea20: 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
ea30: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
ea40: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
ea50: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
ea60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
ea70: 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74           to halt
ea80: 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e   after processin
ea90: 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64  g at most one ad
eaa0: 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 0a  ditional row of.
eab0: 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
eac0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d  ..**.** {F12272}
ead0: 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
eae0: 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
eaf0: 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
eb00: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
eb10: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
eb20: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
eb30: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
eb40: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
eb50: 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66  *.** {U12279} If
eb60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
eb70: 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
eb80: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
eb90: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
eba0: 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
ebb0: 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
ebc0: 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
ebd0: 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
ebe0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ebf0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ec00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
ec10: 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
ec20: 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
ec30: 6d 70 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a  mplete {F10510}.
ec40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
ec50: 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
ec60: 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  for command-line
ec70: 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
ec80: 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
ec90: 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
eca0: 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
ecb0: 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51  rm complete a SQ
ecc0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
ecd0: 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
ece0: 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
ecf0: 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
ed00: 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
ed10: 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
ed20: 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ng.  These routi
ed30: 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  nes return true 
ed40: 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
ed50: 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
ed60: 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
ed70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
ed80: 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
ed90: 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
eda0: 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
edb0: 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
edc0: 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
edd0: 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20   not a fragment 
ede0: 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54  of a.** CREATE T
edf0: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
ee00: 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68  .  Semicolons th
ee10: 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
ee20: 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
ee30: 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
ee40: 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
ee50: 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
ee60: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
ee70: 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
ee80: 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
ee90: 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
eea0: 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
eeb0: 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
eec0: 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
eed0: 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
eee0: 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
eef0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
ef00: 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
ef10: 20 53 51 4c 20 61 6e 64 0a 2a 2a 20 73 6f 20 77   SQL and.** so w
ef20: 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
ef30: 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
ef40: 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
ef50: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
ef60: 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65  .** {F10511} The
ef70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
ef80: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
ef90: 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e  complete16() fun
efa0: 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ctions.**       
efb0: 20 20 20 72 65 74 75 72 6e 20 74 72 75 65 20 28     return true (
efc0: 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64  non-zero) if and
efd0: 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73   only if the las
efe0: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  t.**          no
eff0: 6e 2d 77 68 69 74 65 73 70 61 63 65 20 74 6f 6b  n-whitespace tok
f000: 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75  en in their inpu
f010: 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  t is a semicolon
f020: 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
f030: 20 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77    is not in betw
f040: 65 65 6e 20 74 68 65 20 42 45 47 49 4e 20 61 6e  een the BEGIN an
f050: 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54  d END of a CREAT
f060: 45 20 54 52 49 47 47 45 52 0a 2a 2a 20 20 20 20  E TRIGGER.**    
f070: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e        statement.
f080: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
f090: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31  NS:.**.** {U1051
f0a0: 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  2} The input to 
f0b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f0c0: 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  () must be a zer
f0d0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
f0e0: 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
f0f0: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  tring..**.** {U1
f100: 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
f110: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  to sqlite3_compl
f120: 65 74 65 31 36 28 29 20 6d 75 73 74 20 62 65 20  ete16() must be 
f130: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
f140: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
f150: 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
f160: 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
f170: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f180: 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
f190: 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
f1a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f1b0: 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
f1c0: 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
f1d0: 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
f1e0: 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
f1f0: 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
f200: 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a  Errors {F12310}.
f210: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
f220: 6e 65 20 69 64 65 6e 74 69 66 69 65 73 20 61 20  ne identifies a 
f230: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
f240: 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 0a  n that might be.
f250: 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  ** invoked whene
f260: 76 65 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69  ver an attempt i
f270: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
f280: 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
f290: 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72  .** that another
f2a0: 20 74 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65   thread or proce
f2b0: 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
f2c0: 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
f2d0: 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
f2e0: 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
f2f0: 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
f300: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
f310: 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
f320: 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
f330: 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
f340: 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65   lock..** If the
f350: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
f360: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
f370: 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b   the.** callback
f380: 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
f390: 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
f3a0: 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20 66 69 72  nts.  The.** fir
f3b0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
f3c0: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  he handler is a 
f3d0: 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
f3e0: 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
f3f0: 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
f400: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
f410: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 65 20 73   routine.  The s
f420: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f430: 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  o.** the handler
f440: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
f450: 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
f460: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
f470: 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
f480: 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
f490: 6e 67 20 65 76 65 6e 74 2e 20 20 20 49 66 20 74  ng event.   If t
f4a0: 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
f4b0: 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
f4c0: 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
f4d0: 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
f4e0: 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
f4f0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
f500: 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
f510: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
f520: 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
f530: 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  urned..** If the
f540: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
f550: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
f560: 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
f570: 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
f580: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
f590: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
f5a0: 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
f5b0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
f5c0: 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
f5d0: 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
f5e0: 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
f5f0: 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62 65 20 69  .** it will be i
f600: 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 72  nvoked when ther
f610: 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
f620: 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53 51 4c 69  tion..** If SQLi
f630: 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
f640: 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
f650: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6f 75  busy handler cou
f660: 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a 2a 2a 20  ld result in.** 
f670: 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
f680: 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
f690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
f6a0: 42 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  BUSY] or.** [SQL
f6b0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
f6c0: 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
f6d0: 76 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a 20 62 75  voking the.** bu
f6e0: 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
f6f0: 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
f700: 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
f710: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
f720: 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
f730: 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
f740: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
f750: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
f760: 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
f770: 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
f780: 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
f790: 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
f7a0: 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
f7b0: 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
f7c0: 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
f7d0: 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
f7e0: 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
f7f0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
f800: 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
f810: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
f820: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
f830: 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
f840: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
f850: 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
f860: 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
f870: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
f880: 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
f890: 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
f8a0: 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
f8b0: 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
f8c0: 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
f8d0: 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
f8e0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
f8f0: 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
f900: 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
f910: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
f920: 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
f930: 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
f940: 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
f950: 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
f960: 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  roceed..**.** Th
f970: 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
f980: 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
f990: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
f9a0: 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
f9b0: 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
f9c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f9d0: 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
f9e0: 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
f9f0: 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
fa00: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
fa10: 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
fa20: 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
fa30: 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
fa40: 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
fa50: 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
fa60: 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
fa70: 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
fa80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
fa90: 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
faa0: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
fab0: 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
fac0: 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
fad0: 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
fae0: 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
faf0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
fb00: 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
fb10: 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
fb20: 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e  rs.  If it is un
fb30: 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
fb40: 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
fb50: 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
fb60: 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
fb70: 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
fb80: 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
fb90: 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
fba0: 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
fbb0: 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
fbc0: 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
fbd0: 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
fbe0: 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
fbf0: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
fc00: 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72  OCKED].  This er
fc10: 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
fc20: 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
fc30: 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
fc40: 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
fc50: 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
fc60: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
fc70: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76  ww.sqlite.org/cv
fc80: 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
fc90: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
fca0: 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
fcb0: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
fcc0: 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
fcd0: 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
fce0: 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
fcf0: 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
fd00: 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 54  ortant..**..** T
fd10: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
fd20: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
fd30: 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
fd40: 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65  or each database
fd50: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
fd60: 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
fd70: 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
fd80: 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 20  rs any previous 
fd90: 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65 20 74 68  one. .** Note th
fda0: 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
fdb0: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
fdc0: 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  ()] will also se
fdd0: 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74 68  t or clear.** th
fde0: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
fdf0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
fe00: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 31 7d  :.**.** {F12311}
fe10: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
fe20: 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 66 75  sy_handler()] fu
fe30: 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
fe40: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
fe50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
fe60: 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 64 61 74  lback in the dat
fe70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fe80: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
fe90: 68 65 20 31 73 74 0a 2a 2a 20 20 20 20 20 20 20  he 1st.**       
fea0: 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74     parameter wit
feb0: 68 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  h a new busy han
fec0: 64 6c 65 72 20 69 64 65 6e 74 69 66 69 65 64 20  dler identified 
fed0: 62 79 20 74 68 65 20 32 6e 64 20 61 6e 64 20 33  by the 2nd and 3
fee0: 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rd.**          p
fef0: 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
ff00: 20 7b 46 31 32 33 31 32 7d 20 54 68 65 20 64 65   {F12312} The de
ff10: 66 61 75 6c 74 20 62 75 73 79 20 68 61 6e 64 6c  fault busy handl
ff20: 65 72 20 66 6f 72 20 6e 65 77 20 64 61 74 61 62  er for new datab
ff30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
ff40: 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
ff50: 46 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f  F12314} When two
ff60: 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73   or more databas
ff70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 61  e connection sha
ff80: 72 65 20 61 20 5b 73 71 6c 69 74 65 33 5f 65 6e  re a [sqlite3_en
ff90: 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
ffa0: 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65  e | common cache
ffb0: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
ffc0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
ffd0: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
ffe0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72   connection curr
fff0: 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20  ently using.**  
10000 20 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68          the cach
10010 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  e is invoked whe
10020 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f  n the cache enco
10030 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a  unters a lock..*
10040 2a 0a 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66  *.** {F12316} If
10050 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
10060 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
10070 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
10080 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
10090 20 20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61     interface tha
100a0 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c  t provoked the l
100b0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c  ocking event wil
100c0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
100d0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 55 53       [SQLITE_BUS
100e0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  Y]..**.** {F1231
100f0 38 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  8} SQLite will i
10100 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20  nvokes the busy 
10110 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f  handler with two
10120 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68   arguments which
10130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
10140 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
10150 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
10160 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
10170 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
10180 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
10190 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
101a0 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
101b0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
101c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
101d0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
101e0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
101f0 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
10200 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49   event..**.** LI
10210 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
10220 20 7b 55 31 32 33 31 39 7d 20 41 20 62 75 73 79   {U12319} A busy
10230 20 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c 64 20   handler should 
10240 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f 73 65 20 74  not call close t
10250 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
10260 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
10270 20 20 20 6f 72 20 70 72 65 70 61 72 65 64 20 73     or prepared s
10280 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 6e  tatement that in
10290 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
102a0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
102b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
102c0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
102d0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
102e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
102f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
10300 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31  Busy Timeout {F1
10310 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2340}.**.** This
10320 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
10330 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10340 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
10350 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20 73 6c  dler].** that sl
10360 65 65 70 73 20 66 6f 72 20 61 20 77 68 69 6c 65  eeps for a while
10370 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62 6c 65   when a.** table
10380 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65   is locked.  The
10390 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20 73 6c   handler will sl
103a0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
103b0 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61 74 20  es until .** at 
103c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
103d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
103e0 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20 64 6f  ing have been do
103f0 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20 41 66 74  ne. {F12343} Aft
10400 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c 6c 69  er.** "ms" milli
10410 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
10420 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c 65 72  ing, the handler
10430 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
10440 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71 6c 69  .** causes [sqli
10450 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
10460 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
10470 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
10480 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
10490 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
104a0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
104b0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
104c0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
104d0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
104e0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
104f0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  lers..**.** Ther
10500 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
10510 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
10520 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
10530 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
10540 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 49 66   connection.  If
10550 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
10560 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69 6e 65  ndler was define
10570 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20 5b 73  d  .** (using [s
10580 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10590 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
105a0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
105b0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
105c0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
105d0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
105e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
105f0 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54  **.** {F12341} T
10600 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
10610 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63  _timeout()] func
10620 74 69 6f 6e 20 6f 76 65 72 72 69 64 65 73 20 61  tion overrides a
10630 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20  ny prior.**     
10640 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75       [sqlite3_bu
10650 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72  sy_timeout()] or
10660 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10670 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e  andler()] settin
10680 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  g.**          on
10690 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
106a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
106b0 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66  *.** {F12343} If
106c0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
106d0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
106e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
106f0 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20  s less than.**  
10700 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c          or equal
10710 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   to zero, then t
10720 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
10730 69 73 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68  is cleared so th
10740 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  at.**          a
10750 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f  ll subsequent lo
10760 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d  cking events imm
10770 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20  ediately return 
10780 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
10790 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66  *.** {F12344} If
107a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
107b0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
107c0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
107d0 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20  s a positive.** 
107e0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
107f0 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68  N, then a busy h
10800 61 6e 64 6c 65 72 20 69 73 20 73 65 74 20 74 68  andler is set th
10810 61 74 20 72 65 70 65 61 74 65 64 6c 79 20 63 61  at repeatedly ca
10820 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
10830 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
10840 68 6f 64 20 69 6e 20 74 68 65 20 56 46 53 20 69  hod in the VFS i
10850 6e 74 65 72 66 61 63 65 20 75 6e 74 69 6c 20 65  nterface until e
10860 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 20 20 20  ither the.**    
10870 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72        lock clear
10880 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63  s or until the c
10890 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20  umulative sleep 
108a0 74 69 6d 65 20 72 65 70 6f 72 74 65 64 20 62 61  time reported ba
108b0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ck.**          b
108c0 79 20 78 53 6c 65 65 70 28 29 20 65 78 63 65 65  y xSleep() excee
108d0 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  ds N millisecond
108e0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
108f0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
10900 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
10910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10920 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
10930 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
10940 69 6e 67 20 51 75 65 72 69 65 73 20 7b 46 31 32  ing Queries {F12
10950 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  370}.**.** Defin
10960 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
10970 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
10980 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
10990 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
109a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
109b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
109c0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
109d0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
109e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
109f0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
10a00 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
10a10 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
10a20 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
10a30 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
10a40 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
10a50 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
10a60 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
10a70 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
10a80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
10a90 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
10aa0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
10ab0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
10ac0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
10ad0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
10ae0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
10af0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
10b00 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
10b10 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
10b20 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
10b30 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
10b40 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
10b50 67 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 28  gs.  There are (
10b60 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
10b70 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 0a  in the array.  .
10b80 2a 2a 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  ** The first M p
10b90 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 20 74 6f  ointers point to
10ba0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
10bb0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 0a 2a   strings that .*
10bc0 2a 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61  * contain the na
10bd0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
10be0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
10bf0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
10c00 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
10c10 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 0a 2a  results.  NULL.*
10c20 2a 20 76 61 6c 75 65 73 20 61 72 65 20 67 69 76  * values are giv
10c30 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
10c40 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
10c50 75 65 73 20 61 72 65 20 69 6e 0a 2a 2a 20 74 68  ues are in.** th
10c60 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
10c70 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
10c80 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
10c90 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  as returned by.*
10ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
10cb0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
10cc0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10cd0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 73 20 6f  might consists o
10ce0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
10cf0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
10d00 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
10d10 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
10d20 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
10d30 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
10d40 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
10d50 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
10d60 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
10d70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
10d80 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
10d90 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70  *.** As an examp
10da0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
10db0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
10dc0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
10dd0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
10de0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
10df0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
10e00 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
10e10 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
10e20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
10e30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
10e40 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
10e50 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
10e60 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
10e70 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
10e80 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
10e90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
10ea0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
10eb0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
10ec0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
10ed0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
10ee0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
10ef0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
10f00 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
10f10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
10f20 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
10f30 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
10f40 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
10f50 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
10f60 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
10f70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
10f80 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
10f90 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
10fa0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
10fb0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
10fc0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
10fd0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
10fe0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
10ff0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11000 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
11010 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
11020 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
11030 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
11040 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
11050 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
11060 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11070 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
11080 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
11090 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
110a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
110b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
110c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
110d0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
110e0 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
110f0 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
11100 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
11110 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
11120 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
11130 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
11140 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
11150 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72  meter.  It retur
11160 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
11170 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
11180 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
11190 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
111a0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
111b0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
111c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
111d0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20  ing the result, 
111e0 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61  it should .** pa
111f0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ss the pointer t
11200 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  o the result tab
11210 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  le to sqlite3_fr
11220 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
11230 64 65 72 20 74 6f 20 0a 2a 2a 20 72 65 6c 65 61  der to .** relea
11240 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
11250 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
11260 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
11270 20 77 61 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71   way the .** [sq
11280 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11290 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
112a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
112b0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
112c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
112d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
112e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
112f0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
11300 79 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  y .** [sqlite3_f
11310 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
11320 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
11330 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
11340 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
11350 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11360 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
11370 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
11380 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
11390 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
113a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
113b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
113c0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
113d0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
113e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
113f0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
11400 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
11410 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
11420 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
11430 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
11440 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
11450 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
11460 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
11470 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
11480 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
11490 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
114a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
114b0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
114c0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
114d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
114e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
114f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
11500 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a  3_errmsg()]..**.
11510 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
11520 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66  *.** {F12371} If
11530 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f   a [sqlite3_get_
11540 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61  table()] fails a
11550 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11560 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  on, then.**     
11570 20 20 20 20 20 69 74 20 66 72 65 65 73 20 74 68       it frees th
11580 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75  e result table u
11590 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f  nder constructio
115a0 6e 2c 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a  n, aborts the.**
115b0 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20            query 
115c0 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70  in process, skip
115d0 73 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  s any subsequent
115e0 20 71 75 65 72 69 65 73 2c 20 73 65 74 73 20 74   queries, sets t
115f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  he.**          *
11600 72 65 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70  resultp output p
11610 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61  ointer to NULL a
11620 6e 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  nd returns [SQLI
11630 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
11640 20 7b 46 31 32 33 37 33 7d 20 49 66 20 74 68 65   {F12373} If the
11650 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74   ncolumn paramet
11660 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67  er to [sqlite3_g
11670 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e  et_table()] is n
11680 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  ot NULL.**      
11690 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
116a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77  3_get_table()] w
116b0 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20  rite the number 
116c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
116d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
116e0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
116f0 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c  query into *ncol
11700 75 6d 6e 20 69 66 20 74 68 65 20 71 75 65 72 79  umn if the query
11710 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
11720 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74  successful (if t
11730 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
11740 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a  rns SQLITE_OK)..
11750 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49  **.** {F12374} I
11760 66 20 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d  f the nrow param
11770 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
11780 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73  _get_table()] is
11790 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20   not NULL.**    
117a0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
117b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
117c0 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65   write the numbe
117d0 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65  r of rows in the
117e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
117f0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
11800 75 65 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20  uery into *nrow 
11810 69 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a  if the query is.
11820 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63  **          succ
11830 65 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66  essful (if the f
11840 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11850 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a  SQLITE_OK)..**.*
11860 2a 20 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b  * {F12376} The [
11870 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11880 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65  e()] function se
11890 74 73 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20  ts its *ncolumn 
118a0 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
118b0 20 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20    to the number 
118c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
118d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
118e0 74 68 65 20 71 75 65 72 79 20 69 6e 20 74 68 65  the query in the
118f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
11900 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74   parameter, or t
11910 6f 20 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75  o zero if the qu
11920 65 72 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61  ery in sql has a
11930 6e 20 65 6d 70 74 79 0a 2a 2a 20 20 20 20 20 20  n empty.**      
11940 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2e 0a      result set..
11950 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
11960 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
11970 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
11980 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
11990 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
119a0 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
119b0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
119c0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
119d0 72 20 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20  r ***pResult,   
119e0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
119f0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
11a00 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20  int *nrow,      
11a10 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
11a20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
11a30 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
11a40 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20   int *ncolumn,  
11a50 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
11a60 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
11a70 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
11a80 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
11a90 73 67 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72  sg         /* Er
11aa0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
11ab0 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
11ac0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
11ad0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
11ae0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11af0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
11b00 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
11b10 6e 63 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d  nctions {F17400}
11b20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
11b30 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
11b40 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
11b50 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
11b60 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
11b70 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
11b80 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
11b90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
11ba0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
11bb0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
11bc0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
11bd0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
11be0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
11bf0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
11c00 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
11c10 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
11c20 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
11c30 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
11c40 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
11c50 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
11c60 28 29 5d 2e 20 20 20 42 6f 74 68 20 72 6f 75 74  ()].   Both rout
11c70 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
11c80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
11c90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11ca0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
11cb0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
11cc0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
11cd0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
11ce0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49   string..**.** I
11cf0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
11d00 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
11d10 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
11d20 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
11d30 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
11d40 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
11d50 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
11d60 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
11d70 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
11d80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11d90 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
11da0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
11db0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11dc0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
11dd0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
11de0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
11df0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
11e00 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
11e10 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
11e20 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
11e30 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
11e40 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
11e50 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
11e60 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
11e70 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
11e80 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
11e90 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
11ea0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
11eb0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
11ec0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
11ed0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
11ee0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
11ef0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
11f00 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
11f10 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
11f20 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
11f30 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
11f40 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
11f50 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
11f60 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
11f70 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
11f80 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
11f90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
11fa0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
11fb0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
11fc0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
11fd0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
11fe0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
11ff0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
12000 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
12010 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
12020 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
12030 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
12040 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
12050 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
12060 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
12070 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
12080 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
12090 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
120a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
120b0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
120c0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
120d0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
120e0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
120f0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
12100 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
12110 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
12120 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
12130 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
12140 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
12150 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
12160 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
12170 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
12180 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
12190 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
121a0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
121b0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
121c0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
121d0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
121e0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
121f0 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69  *.** The %q opti
12200 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
12210 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
12220 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
12230 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
12240 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
12250 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
12260 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
12270 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
12280 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
12290 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
122a0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
122b0 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f   literal.  By do
122c0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
122d0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
122e0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
122f0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
12300 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
12310 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
12320 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
12330 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73  or example, so s
12340 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  ome string varia
12350 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ble contains tex
12360 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
12370 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12380 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
12390 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
123a0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
123b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
123c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
123d0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
123e0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
123f0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
12400 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12410 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
12420 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
12430 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
12440 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
12450 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
12460 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
12470 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
12480 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
12490 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
124a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
124b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
124c0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
124d0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
124e0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
124f0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
12500 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
12510 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
12520 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
12530 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
12540 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
12550 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
12560 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
12570 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
12580 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
12590 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
125a0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
125b0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
125c0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
125d0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
125e0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
125f0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
12600 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
12610 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
12620 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
12630 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
12640 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
12650 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
12660 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
12670 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
12680 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
12690 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
126a0 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75  rule you.** shou
126b0 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ld always use %q
126c0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
126d0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
126e0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
126f0 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a   .** literal..**
12700 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
12710 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
12720 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
12730 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
12740 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
12750 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
12760 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72  otal string.  Or
12770 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
12780 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e  r in the argumen
12790 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e  t.** list is a N
127a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
127b0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
127c0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
127d0 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71  hout single.** q
127e0 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20  uotes) in place 
127f0 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e  of the %Q option
12800 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72  . {END}  So, for
12810 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
12820 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
12830 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12840 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
12850 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
12860 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
12870 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
12880 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
12890 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
128a0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
128b0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
128c0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
128d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
128e0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
128f0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
12900 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
12910 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
12920 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
12930 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
12940 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
12950 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
12960 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d  ** The "%z" form
12970 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
12980 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65  rks exactly like
12990 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a   "%s" with the.*
129a0 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
129b0 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
129c0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
129d0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
129e0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
129f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
12a00 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
12a10 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45  input string. {E
12a20 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ND}.**.** INVARI
12a30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
12a40 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  403}  The [sqlit
12a50 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e  e3_mprintf()] an
12a60 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  d [sqlite3_vmpri
12a70 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
12a80 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  s.**           r
12a90 65 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69  eturn either poi
12aa0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
12ab0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
12ac0 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a  trings held in.*
12ad0 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  *           memo
12ae0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
12af0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12b00 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e  ()] or NULL poin
12b10 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20  ters if.**      
12b20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b       a call to [
12b30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12b40 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ] fails..**.** {
12b50 46 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71  F17406}  The [sq
12b60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12b70 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74  ] interface writ
12b80 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  es a zero-termin
12b90 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
12ba0 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
12bb0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70  nto the buffer p
12bc0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
12bd0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12be0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70  r.**           p
12bf0 72 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65  rovided that the
12c00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
12c10 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
12c20 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
12c30 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69  7407}  The [sqli
12c40 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
12c50 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
12c60 6f 74 20 77 72 69 74 65 73 20 73 6c 6f 74 73 20  ot writes slots 
12c70 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
12c80 69 74 73 20 6f 75 74 70 75 74 20 62 75 66 66 65  its output buffe
12c90 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61  r (the second pa
12ca0 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65  rameter) outside
12cb0 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20   the range.**   
12cc0 20 20 20 20 20 20 20 20 6f 66 20 30 20 74 68 72          of 0 thr
12cd0 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20  ough N-1 (where 
12ce0 4e 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  N is the first p
12cf0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20  arameter).**    
12d00 20 20 20 20 20 20 20 72 65 67 61 72 64 6c 65 73         regardles
12d10 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20  s of the length 
12d20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a  of the string.**
12d30 20 20 20 20 20 20 20 20 20 20 20 72 65 71 75 65             reque
12d40 73 74 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d  sted by the form
12d50 61 74 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  at specification
12d60 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61 72 20  ..**   .*/.char 
12d70 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
12d80 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
12d90 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
12da0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
12db0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
12dc0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
12dd0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
12de0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
12df0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
12e00 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
12e10 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
12e20 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a  m {F17300}.**.**
12e30 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
12e40 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
12e50 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
12e60 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
12e70 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
12e80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
12e90 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
12ea0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
12eb0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
12ec0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
12ed0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
12ee0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
12ef0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
12f00 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
12f10 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
12f20 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
12f30 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
12f40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12f50 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
12f60 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
12f70 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
12f80 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
12f90 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
12fa0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
12fb0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
12fc0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
12fd0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
12fe0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
12ff0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
13000 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
13010 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
13020 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
13030 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
13040 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
13050 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
13060 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
13070 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
13080 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
13090 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
130a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
130b0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
130c0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
130d0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
130e0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
130f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
13100 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
13110 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
13120 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
13130 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
13140 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
13150 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
13160 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
13170 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
13180 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
13190 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
131a0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
131b0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
131c0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
131d0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
131e0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
131f0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
13200 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
13210 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
13220 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
13230 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
13240 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
13250 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
13260 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
13270 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
13280 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
13290 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
132a0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
132b0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
132c0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
132d0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
132e0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
132f0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
13300 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
13310 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
13320 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  free()..**.** Th
13330 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
13340 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
13350 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
13360 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
13370 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
13380 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
13390 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
133a0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
133b0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
133c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
133d0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
133e0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
133f0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68  arameter.  If th
13400 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13410 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
13420 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
13430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
13440 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
13450 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
13460 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
13470 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
13480 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
13490 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
134a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
134b0 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e  .** If the secon
134c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
134d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
134e0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
134f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
13500 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
13510 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
13520 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
13530 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
13540 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
13550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
13560 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
13570 0a 2a 2a 20 53 71 6c 69 74 65 33 5f 72 65 61 6c  .** Sqlite3_real
13580 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
13590 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
135a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
135b0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
135c0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
135d0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
135e0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
135f0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66  available..** If
13600 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
13610 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
13620 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
13630 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
13640 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
13650 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
13660 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
13670 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
13680 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
13690 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
136a0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
136b0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
136c0 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  d..** If sqlite3
136d0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
136e0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
136f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
13700 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
13710 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  ed..**.** The me
13720 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
13730 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13740 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
13750 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
13760 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
13770 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
13780 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e  te boundary. {EN
13790 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  D}.**.** The def
137a0 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
137b0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 65  ion.** of the me
137c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
137d0 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 20 74  subsystem uses t
137e0 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
137f0 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e 64 20 66 72  lloc().** and fr
13800 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
13810 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
13820 6c 69 62 72 61 72 79 2e 20 7b 46 31 37 33 38 32  library. {F17382
13830 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a  } However, if .*
13840 2a 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  * SQLite is comp
13850 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 6f  iled with the fo
13860 6c 6c 6f 77 69 6e 67 20 43 20 70 72 65 70 72 6f  llowing C prepro
13870 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a  cessor macro.**.
13880 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20  ** <blockquote> 
13890 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
138a0 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f  ZE=<i>NNN</i> </
138b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
138c0 2a 20 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f  * where <i>NNN</
138d0 69 3e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  i> is an integer
138e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72  , then SQLite cr
138f0 65 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  eate a static.**
13900 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
13910 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79  st <i>NNN</i> by
13920 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20  tes in size and 
13930 75 73 65 20 74 68 61 74 20 61 72 72 61 79 0a 2a  use that array.*
13940 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
13950 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
13960 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
13970 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f  . {END}  Additio
13980 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  nal.** memory al
13990 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 20  locator options 
139a0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
139b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
139c0 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
139d0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
139e0 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
139f0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
13a00 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
13a10 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
13a20 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
13a30 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
13a40 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
13a50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
13a60 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
13a70 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
13a80 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
13a90 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
13aa0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
13ab0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
13ac0 63 61 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a  cators can be.**
13ad0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
13ae0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
13af0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
13b00 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
13b10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
13b20 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
13b30 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
13b40 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
13b50 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
13b60 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
13b70 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
13b80 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
13b90 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
13ba0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
13bb0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
13bc0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
13bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
13be0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
13bf0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
13c00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
13c10 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
13c20 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
13c30 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
13c40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
13c50 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
13c60 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
13c70 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7303}  The [sqli
13c80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
13c90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
13ca0 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
13cb0 72 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  r to .**        
13cc0 20 20 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64     newly checked
13cd0 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74  -out block of at
13ce0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f   least N bytes o
13cf0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  f memory.**     
13d00 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d        that is 8-
13d10 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 0a 2a  byte aligned, .*
13d20 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
13d30 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  t returns NULL i
13d40 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
13d50 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65  o fulfill the re
13d60 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  quest..**.** {F1
13d70 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69  7304}  The [sqli
13d80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
13d90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
13da0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
13db0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
13dc0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
13dd0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e  r equal to zero.
13de0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20  .**.** {F17305} 
13df0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   The [sqlite3_fr
13e00 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ee(P)] interface
13e10 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79   releases memory
13e20 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
13e30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
13e40 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13e50 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
13e60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
13e70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ,.**           m
13e80 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62  aking it availab
13e90 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a  le for reuse..**
13ea0 0a 2a 2a 20 7b 46 31 37 33 30 36 7d 20 20 41 20  .** {F17306}  A 
13eb0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
13ec0 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20  _free(NULL)] is 
13ed0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
13ee0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 30 7d  ..**.** {F17310}
13ef0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
13f00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
13f10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
13f20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
13f30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
13f40 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a  te3_malloc(N)]..
13f50 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 32 7d 20 20  **.** {F17312}  
13f60 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
13f70 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d  e3_realloc(P,0)]
13f80 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
13f90 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
13fa0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
13fb0 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a  3_free(P)]..**.*
13fc0 2a 20 7b 46 31 37 33 31 35 7d 20 20 54 68 65 20  * {F17315}  The 
13fd0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
13fe0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13ff0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  ()], [sqlite3_re
14000 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
14010 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69         and [sqli
14020 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
14030 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72  all of its memor
14040 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64  y allocation and
14050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65  .**           de
14060 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14070 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 38 7d  ..**.** {F17318}
14080 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72    The [sqlite3_r
14090 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74  ealloc(P,N)] int
140a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
140b0 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a  ither a pointer.
140c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
140d0 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b  a block of check
140e0 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66  ed-out memory of
140f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
14100 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
14110 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
14120 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
14130 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
14140 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d  ..**.** {F17321}
14150 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
14160 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
14170 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
14180 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
14190 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
141a0 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74  copies the first
141b0 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74   K bytes of cont
141c0 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20  ent from P into 
141d0 74 68 65 20 6e 65 77 6c 79 20 61 6c 6c 6f 63 61  the newly alloca
141e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
141f0 20 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20   where K is the 
14200 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20  lesser of N and 
14210 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
14220 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
14230 7b 46 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b  {F17322}  When [
14240 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14250 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
14260 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
14270 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
14280 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73          releases
14290 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
142a0 2a 0a 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57  *.** {F17323}  W
142b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
142c0 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
142d0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66  ns NULL, the buf
142e0 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20  fer P is.**     
142f0 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69        not modifi
14300 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a  ed or released..
14310 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
14320 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33 35 30  S:.**.** {U17350
14330 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  }  The pointer a
14340 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
14350 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
14360 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14370 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
14380 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72    must be either
14390 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 61 20   NULL or else a 
143a0 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
143b0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
143c0 20 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63             invoc
143d0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
143e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
143f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14400 29 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 20  )] that has.**  
14410 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65           not bee
14420 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
14430 2a 20 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20  * {U17351}  The 
14440 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
14450 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
14460 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 20 0a  te any part of .
14470 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62  **           a b
14480 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
14490 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
144a0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
144b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
144c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
144d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
144e0 63 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  c()]..**.*/.void
144f0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
14500 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
14510 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
14520 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
14530 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
14540 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
14550 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
14560 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
14570 20 7b 46 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F17370}.**.** 
14580 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
14590 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
145a0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
145b0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
145c0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
145d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
145e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
145f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
14600 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 74 68 65 20  alloc()].** the 
14610 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14620 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c  n subsystem incl
14630 75 64 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  uded within the 
14640 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  SQLite..**.** IN
14650 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14660 7b 46 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71  {F17371} The [sq
14670 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14680 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
14690 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
146a0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
146b0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 63  ytes of memory c
146c0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
146d0 64 69 6e 67 20 0a 2a 2a 20 20 20 20 20 20 20 20  ding .**        
146e0 20 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20    (malloced but 
146f0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a  not freed)..**.*
14700 2a 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b  * {F17373} The [
14710 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14720 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
14730 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
14740 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20  maximum.**      
14750 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71      value of [sq
14760 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14770 64 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20  d()] .**        
14780 20 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68    since the high
14790 2d 77 61 74 65 72 20 6d 61 72 6b 20 77 61 73 20  -water mark was 
147a0 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a  last reset..**.*
147b0 2a 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76  * {F17374} The v
147c0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
147d0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
147e0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
147f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14800 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14810 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
14820 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20  ny overhead.**  
14830 20 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79          added by
14840 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
14850 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
14860 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14870 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
14880 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
14890 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
148a0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
148b0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
148c0 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
148d0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
148e0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
148f0 6c 6c 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 37 33  ll..** .** {F173
14900 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68  75} The memory h
14910 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
14920 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
14930 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
14940 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
14950 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14960 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
14970 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
14980 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
14990 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
149a0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
149b0 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65  true.  The value
149c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
149d0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
149e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
149f0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
14a00 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
14a10 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20            prior 
14a20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
14a30 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
14a40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
14a50 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
14a60 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
14a70 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14a80 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
14a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
14aa0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
14ab0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
14ac0 20 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20   {F17390}.**.** 
14ad0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
14ae0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
14af0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
14b00 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
14b10 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
14b20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f  select random RO
14b30 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74  WIDs when insert
14b40 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
14b50 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
14b60 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
14b70 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
14b80 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54  ssible ROWID.  T
14b90 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
14ba0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
14bb0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
14bc0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
14bd0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
14be0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
14bf0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
14c00 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
14c10 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
14c20 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
14c30 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
14c40 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
14c50 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
14c60 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
14c70 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
14c80 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
14c90 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
14ca0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
14cb0 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
14cc0 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
14cd0 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
14ce0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
14cf0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
14d00 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
14d10 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
14d20 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
14d30 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
14d40 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
14d50 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
14d60 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
14d70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
14d80 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
14d90 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
14da0 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
14db0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14dc0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
14dd0 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
14de0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
14df0 2a 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68  *.** {F17392} Th
14e00 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  e [sqlite3_rando
14e10 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65  mness(N,P)] inte
14e20 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
14e30 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
14e40 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79      high-quality
14e50 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
14e60 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
14e70 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
14e80 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
14e90 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
14ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
14eb0 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
14ec0 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
14ed0 63 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a  cks {F12500}.**.
14ee0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
14ef0 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68  registers a auth
14f00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
14f10 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
14f20 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
14f30 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
14f40 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
14f50 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  t argument..** T
14f60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
14f70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14f80 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
14f90 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
14fa0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
14fb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
14fc0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
14fd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
14fe0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
14ff0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
15000 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
15010 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
15020 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70   At various.** p
15030 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
15040 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
15050 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
15060 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
15070 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
15080 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
15090 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
150a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
150b0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
150c0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
150d0 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61   allowed.  The a
150e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
150f0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
15100 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
15110 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
15120 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
15130 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
15140 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
15150 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
15160 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
15170 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
15180 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
15190 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
151a0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
151b0 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
151c0 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
151d0 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
151e0 65 72 72 6f 72 2e 20 20 20 49 66 20 74 68 65 20  error.   If the 
151f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15200 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
15210 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
15220 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
15230 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
15240 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
15250 59 5d 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  Y].** then [sqli
15260 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
15270 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
15280 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
15290 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
152a0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
152b0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
152c0 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
152d0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
152e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
152f0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
15300 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
15310 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
15320 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62    When the callb
15330 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
15340 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
15350 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
15360 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
15370 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
15380 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
15390 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
153a0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
153b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
153c0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
153d0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
153e0 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
153f0 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51  izer code is [SQ
15400 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
15410 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
15420 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
15430 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
15440 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
15450 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
15460 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
15470 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
15480 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
15490 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
154a0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
154b0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
154c0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
154d0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
154e0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
154f0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
15500 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
15510 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
15520 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
15530 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
15540 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
15550 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a  of a table..**.*
15560 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
15570 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
15580 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15590 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
155a0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
155b0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
155c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
155d0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a  er() interface..
155e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
155f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
15600 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
15610 74 65 67 65 72 20 0a 2a 2a 20 5b 53 51 4c 49 54  teger .** [SQLIT
15620 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
15630 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
15640 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
15650 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f  lar action.** to
15660 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
15670 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
15680 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
15690 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
156a0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
156b0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
156c0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a  s that contain .
156d0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  ** additional de
156e0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
156f0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
15700 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  horized..**.** A
15710 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
15720 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
15730 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
15740 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
15750 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
15760 6e 20 75 6e 74 72 75 73 74 65 64 0a 2a 2a 20 73  n untrusted.** s
15770 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
15780 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
15790 61 74 65 6d 65 6e 74 73 20 64 6f 20 6e 6f 74 20  atements do not 
157a0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
157b0 74 61 0a 2a 2a 20 74 68 61 74 20 74 68 65 79 20  ta.** that they 
157c0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
157d0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
157e0 74 68 65 79 20 64 6f 20 6e 6f 74 20 74 72 79 20  they do not try 
157f0 74 6f 0a 2a 2a 20 65 78 65 63 75 74 65 20 6d 61  to.** execute ma
15800 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
15810 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
15820 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
15830 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
15840 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
15850 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
15860 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
15870 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
15880 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
15890 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
158a0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
158b0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
158c0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
158d0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
158e0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
158f0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
15900 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
15910 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
15920 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
15930 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
15940 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
15950 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
15960 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
15970 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
15980 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
15990 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
159a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
159b0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
159c0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
159d0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
159e0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
159f0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
15a00 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
15a10 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
15a20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
15a30 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
15a40 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
15a50 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
15a60 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
15a70 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
15a80 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
15a90 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
15aa0 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
15ab0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
15ac0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
15ad0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
15ae0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
15af0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
15b00 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
15b10 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
15b20 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
15b30 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73  vious call.  Dis
15b40 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
15b50 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
15b60 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
15b70 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
15b80 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
15b90 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
15ba0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
15bb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15bc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15bd0 6f 6e 6c 79 20 64 75 72 69 6e 67 20 0a 2a 2a 20  only during .** 
15be0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15bf0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
15c00 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
15c10 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
15c20 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
15c30 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
15c40 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
15c50 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  step()]..**.** I
15c60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
15c70 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73   {F12501} The [s
15c80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
15c90 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e  rizer(D,...)] in
15ca0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
15cb0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
15cc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15cd0 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73  ack with databas
15ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
15cf0 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54  **.** {F12502} T
15d00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
15d10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
15d20 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
15d30 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  nts are.**      
15d40 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c      being compil
15d50 65 64 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 33  ed.**.** {F12503
15d60 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
15d70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
15d80 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f  urns any value o
15d90 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
15da0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
15db0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
15dc0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
15dd0 45 4e 59 5d 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ENY] then.**    
15de0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
15df0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
15e00 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
15e10 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a  all that caused.
15e20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
15e30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15e40 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
15e50 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a   fail with an.**
15e60 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
15e70 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
15e80 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  ode and an appro
15e90 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
15ea0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  sage..**.** {F12
15eb0 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75  504} When the au
15ec0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15ed0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
15ee0 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61  E_OK], the opera
15ef0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
15f00 20 64 65 73 63 72 69 62 65 64 20 69 73 20 63 6f   described is co
15f10 64 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a  ded normally..**
15f20 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68 65  .** {F12505} Whe
15f30 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  n the authorizer
15f40 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15f50 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
15f60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
15f80 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
15f90 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
15fa0 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20  caused the.**   
15fb0 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
15fc0 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
15fd0 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20  n shall fail.** 
15fe0 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e           with an
15ff0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
16000 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
16010 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  n error message.
16020 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c  **          expl
16030 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65  aining that acce
16040 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a  ss is denied..**
16050 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66 20  .** {F12506} If 
16060 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16070 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
16080 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16090 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
160a0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
160b0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  s [SQLITE_READ] 
160c0 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  and the authoriz
160d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
160e0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
160f0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
16100 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  then the prepare
16110 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
16120 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a  onstructed to.**
16130 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74            insert
16140 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
16150 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
16160 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
16170 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20  would have.**   
16180 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64         been read
16190 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
161a0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
161b0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 37  d..**.** {F12507
161c0 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
161d0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
161e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
161f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
16200 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
16210 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20  ck) is anything 
16220 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
16230 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a  TE_READ], then.*
16240 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
16250 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  urn of [SQLITE_I
16260 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73  GNORE] has the s
16270 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53  ame effect as [S
16280 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a 2a 2a  QLITE_DENY]. .**
16290 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65  .** {F12510} The
162a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
162b0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
162c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
162d0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
162e0 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70       the third p
162f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
16300 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16310 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
16320 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  face..**.** {F12
16330 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  511} The second 
16340 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16350 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
16360 69 6e 74 65 67 65 72 20 0a 2a 2a 20 20 20 20 20  integer .**     
16370 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
16380 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
16390 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
163a0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
163b0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
163c0 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a    to be authoriz
163d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31  ed..**.** {F1251
163e0 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72  2} The third thr
163f0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
16400 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
16410 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20  lback are.**    
16420 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
16430 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
16440 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 20  at contain .**  
16450 20 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e          addition
16460 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  al details about
16470 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
16480 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
16490 0a 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63  .** {F12520} Eac
164a0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
164b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
164c0 72 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74  r()] overrides t
164d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
164e0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e  ny previously in
164f0 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a  stalled authoriz
16500 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  er..**.** {F1252
16510 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  1} A NULL author
16520 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
16530 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
16540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
16550 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16560 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d  ..**.** {F12522}
16570 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
16580 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
16590 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
165a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
165b0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
165c0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
165d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
165e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
165f0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
16600 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
16610 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
16620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
16630 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
16640 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a  odes {F12590}.**
16650 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
16660 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
16670 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
16680 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
16690 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
166a0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
166b0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
166c0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
166d0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
166e0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
166f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
16700 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
16710 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
16720 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16730 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
16740 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
16750 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
16760 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
16770 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
16780 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
16790 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
167a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
167b0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
167c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
167d0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
167e0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
167f0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
16800 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
16810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
16820 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
16830 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a  Codes {F12550}.*
16840 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
16850 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16860 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
16870 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
16880 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
16890 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
168a0 6f 20 61 75 74 68 6f 72 69 7a 65 72 20 63 65 72  o authorizer cer
168b0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
168c0 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
168d0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
168e0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
168f0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
16900 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
16910 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
16920 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
16930 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
16940 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
16950 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
16960 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
16970 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
16980 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
16990 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
169a0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
169b0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
169c0 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
169d0 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69  o be .** authori
169e0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
169f0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
16a00 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16a10 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
16a20 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
16a30 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
16a40 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
16a50 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
16a60 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
16a70 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16a80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
16a90 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
16aa0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
16ab0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16ac0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16ad0 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
16ae0 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74  , "temp", .** et
16af0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
16b00 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61  e.  The 6th para
16b10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
16b20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16b30 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
16b40 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
16b50 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
16b60 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
16b70 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
16b80 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
16b90 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
16ba0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
16bb0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 20  s directly from 
16bc0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
16bd0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
16be0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
16bf0 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {F12551} The sec
16c00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
16c10 20 61 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   an .**         
16c20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16c30 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
16c40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20  rizer callback] 
16c50 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74  is always an int
16c60 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
16c70 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
16c80 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
16c90 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
16ca0 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  what action.**  
16cb0 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67          is being
16cc0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
16cd0 2a 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20  ** {F12552} The 
16ce0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
16cf0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 0a 2a  meters to the .*
16d00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16d10 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
16d20 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69  er | authorizati
16d30 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  on callback func
16d40 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
16d50 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65    will be parame
16d60 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
16d70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
16d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
16d90 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68  LITE_COPY | auth
16da0 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20  orizer code] is 
16db0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
16dc0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
16dd0 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65  .** {F12553} The
16de0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
16df0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
16e00 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
16e10 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
16e20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
16e30 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   is the name.** 
16e40 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
16e50 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c  database (exampl
16e60 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e: "main", "temp
16e70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ", etc.) if appl
16e80 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  icable..**.** {F
16e90 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70  12554} The 6th p
16ea0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
16eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16ec0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16ed0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
16ee0 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68   callback] is th
16ef0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
16f00 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d     of the inner-
16f10 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
16f20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
16f30 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
16f40 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63           the acc
16f50 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
16f60 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
16f70 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
16f80 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20  rectly from .** 
16f90 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76           top-lev
16fa0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
16fb0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
16fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
16fe0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
16ff0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
17000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17010 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
17020 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
17030 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17040 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17060 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
17070 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
17080 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17090 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
170a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
170b0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
170c0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
170d0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
170e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
170f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17100 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
17110 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
17120 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
17130 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17140 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17150 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
17160 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
17170 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
17180 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17190 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
171a0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
171b0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
171c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
171d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
171e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
171f0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
17200 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
17210 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
17220 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17230 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
17240 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
17250 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
17260 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17270 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17280 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
17290 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
172a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
172b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
172c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
172d0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
172e0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
172f0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17300 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17310 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17320 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
17330 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
17340 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17350 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17360 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17370 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
17380 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
17390 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
173a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
173b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
173c0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
173d0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
173e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
173f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17410 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
17420 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
17430 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
17440 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17460 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
17470 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
17480 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
17490 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
174a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
174b0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
174c0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
174d0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
174e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
174f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17500 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
17510 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
17520 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
17530 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
17550 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
17560 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
17570 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17580 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17590 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
175a0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
175b0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
175c0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
175d0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
175e0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
175f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
17600 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
17610 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
17620 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17630 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
17640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
17650 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
17660 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
17670 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17680 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
17690 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
176a0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
176b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
176c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
176d0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
176e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
176f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17700 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
17710 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17720 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
17730 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
17740 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
17750 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17760 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17770 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
17780 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
17790 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
177a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
177b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
177c0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
177d0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
177e0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
177f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17800 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17810 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
17820 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
17830 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
17840 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17860 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
17870 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
17880 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17890 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
178a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
178b0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
178c0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
178d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
178e0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
178f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17900 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
17910 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
17920 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
17930 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
17940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17950 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
17960 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e       31   /* Fun
17970 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c  ction Name   NUL
17980 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17990 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
179a0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
179b0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
179c0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
179d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
179e0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
179f0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b  ling Functions {
17a00 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12280}.**.** Th
17a10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
17a20 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
17a30 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
17a40 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
17a50 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
17a60 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
17a70 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
17a80 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
17a90 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
17aa0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
17ab0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
17ac0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
17ad0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
17ae0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
17af0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
17b00 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
17b10 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
17b20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17b30 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
17b40 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
17b50 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
17b60 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
17b70 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
17b80 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
17b90 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
17ba0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
17bb0 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
17bc0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
17bd0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
17be0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
17bf0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
17c00 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
17c10 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
17c20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 0a 2a 2a 20  trigger..** .** 
17c30 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
17c40 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
17c50 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
17c60 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
17c70 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
17c80 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
17c90 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65  es.  The profile
17ca0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
17cb0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
17cc0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
17cd0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
17ce0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
17cf0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
17d00 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
17d10 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
17d20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
17d30 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20  3_profile() API 
17d40 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
17d50 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
17d60 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73  ntal and.** is s
17d70 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
17d80 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61   or removal in a
17d90 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e   future release.
17da0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67  .**.** The trigg
17db0 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61  er reporting fea
17dc0 74 75 72 65 20 6f 66 20 74 68 65 20 74 72 61 63  ture of the trac
17dd0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f  e callback is co
17de0 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65  nsidered.** expe
17df0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
17e00 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
17e10 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20  e or removal in 
17e20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
17e30 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73 69  .** Future versi
17e40 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
17e50 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77  ght also add new
17e60 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
17e70 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e  .** invocations.
17e80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
17e90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31  S:.**.** {F12281
17ea0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
17eb0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
17ec0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74  ed by [sqlite3_t
17ed0 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20  race()] is.**   
17ee0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
17ef0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
17f00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
17f10 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20   execute and.** 
17f20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
17f30 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  r a trigger subp
17f40 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67  rogram first beg
17f50 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ins to run..**.*
17f60 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68 20  * {F12282} Each 
17f70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
17f80 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69  _trace()] overri
17f90 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73  des the previous
17fa0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ly.**          r
17fb0 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20  egistered trace 
17fc0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
17fd0 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20  {F12283} A NULL 
17fe0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64  trace callback d
17ff0 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e  isables tracing.
18000 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20  .**.** {F12284} 
18010 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
18020 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
18030 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
18040 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
18050 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68    the pointer wh
18060 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20  ich was the 3rd 
18070 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
18080 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a  ite3_trace()]..*
18090 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54 68  *.** {F12285} Th
180a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
180b0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
180c0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
180d0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
180e0 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74  rminated UTF8 st
180f0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
18100 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78  the original tex
18110 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  t.**          of
18120 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18130 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73  nt as it was pas
18140 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65  sed into [sqlite
18150 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
18160 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
18170 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f  he equivalent, o
18180 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
18190 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
181a0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  beginning.**    
181b0 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67        of a trigg
181c0 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a  er subprogram..*
181d0 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68  *.** {F12287} Th
181e0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
181f0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18200 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  y [sqlite3_profi
18210 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  le()] is invoked
18220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
18230 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
18240 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
18250 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20  ** {F12288} The 
18260 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
18270 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
18280 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
18290 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
182a0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
182b0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  er to [sqlite3_p
182c0 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rofile()]..**.**
182d0 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73 65   {F12289} The se
182e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
182f0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
18300 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
18310 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
18320 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
18330 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69  ring that contai
18340 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20  ns the complete 
18350 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20  text of.**      
18360 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74      the SQL stat
18370 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20  ement as it was 
18380 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71  processed by [sq
18390 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
183a0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
183b0 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
183c0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30  t..**.** {F12290
183d0 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  } The third para
183e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
183f0 66 69 6c 65 20 20 63 61 6c 6c 62 61 63 6b 20 69  file  callback i
18400 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a  s an estimate.**
18410 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
18420 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
18430 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63  econds of wall-c
18440 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72  lock time requir
18450 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
18460 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74    run the SQL st
18470 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61  atement from sta
18480 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f  rt to finish..*/
18490 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
184a0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
184b0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
184c0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
184d0 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
184e0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
184f0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
18500 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
18510 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
18520 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
18530 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18540 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
18550 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
18560 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F12910}.**.** 
18570 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e  This routine con
18580 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61  figures a callba
18590 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68  ck function - th
185a0 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61  e.** progress ca
185b0 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73  llback - that is
185c0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
185d0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
185e0 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c  g.** running cal
185f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
18600 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
18610 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20  _step()] and.** 
18620 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
18630 6c 65 28 29 5d 2e 20 20 20 41 6e 20 65 78 61 6d  le()].   An exam
18640 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
18650 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69   .** interface i
18660 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
18670 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
18680 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
18690 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72  .** If the progr
186a0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
186b0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
186c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
186d0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
186e0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
186f0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
18700 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
18710 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
18720 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e   GUI dialog box.
18730 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
18740 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31  S:.**.** {F12911
18750 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
18760 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
18770 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
18780 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18790 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
187a0 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
187b0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
187c0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
187d0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
187e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
187f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d  ..**.** {F12912}
18800 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
18810 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18820 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79  d once for every
18830 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20   N virtual.**   
18840 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f         machine o
18850 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20  pcodes, where N 
18860 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
18870 67 75 6d 65 6e 74 20 74 6f 20 0a 2a 2a 20 20 20  gument to .**   
18880 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
18890 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
188a0 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61  dler()] call tha
188b0 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  t registered.** 
188c0 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
188d0 6c 62 61 63 6b 2e 20 20 3c 74 6f 64 6f 3e 57 68  lback.  <todo>Wh
188e0 61 74 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  at if N is less 
188f0 74 68 61 6e 20 31 3f 3c 2f 74 6f 64 6f 3e 0a 2a  than 1?</todo>.*
18900 2a 0a 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68  *.** {F12913} Th
18910 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
18920 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
18930 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
18940 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
18950 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73    argument to [s
18960 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18970 68 61 6e 64 6c 65 72 28 29 5d 2e 0a 2a 2a 0a 2a  handler()]..**.*
18980 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66  * {F12914} The f
18990 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 5b  ourth argument [
189a0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
189b0 5f 68 61 6e 64 6c 65 72 28 29 5d 20 69 73 20 61  _handler()] is a
189c0 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 76 6f 69  .***         voi
189d0 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
189e0 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
189f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
18a00 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65        function e
18a10 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
18a20 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
18a30 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c  12915} If a call
18a40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
18a50 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20  p()] results in 
18a60 66 65 77 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  fewer than.**   
18a70 20 20 20 20 20 20 20 4e 20 6f 70 63 6f 64 65 73         N opcodes
18a80 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
18a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
18aa0 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  n the progress c
18ab0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72  allback is never
18ac0 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a   invoked. {END}.
18ad0 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20  ** .** {F12916} 
18ae0 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73  Every call to [s
18af0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18b00 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20  handler()].**   
18b10 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65         overwrite
18b20 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  s any previously
18b30 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f 67   registered prog
18b40 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
18b50 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20  .** {F12917} If 
18b60 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
18b70 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
18b80 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72   NULL then no pr
18b90 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  ogress.**       
18ba0 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e     handler is in
18bb0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
18bc0 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f  2918} If the pro
18bd0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
18be0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
18bf0 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68  other than 0, th
18c00 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
18c10 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61  he behavior is a
18c20 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   if [sqlite3_int
18c30 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65  errupt()] had be
18c40 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f  en called..*/.vo
18c50 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
18c60 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
18c70 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
18c80 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
18c90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18ca0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
18cb0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
18cc0 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a  tion {F12700}.**
18cd0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18ce0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
18cf0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
18d00 77 68 6f 73 65 20 6e 61 6d 65 0a 2a 2a 20 69 73  whose name.** is
18d10 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 66 69   given by the fi
18d20 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
18d30 0a 2a 2a 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  .** The filename
18d40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
18d50 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
18d60 38 0a 2a 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65  8.** for [sqlite
18d70 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
18d80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
18d90 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
18da0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
18db0 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
18dc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
18dd0 29 5d 2e 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  )]..** An [sqlit
18de0 65 33 2a 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  e3*] handle is u
18df0 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 65 64 20  sually returned 
18e00 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a  in *ppDb, even.*
18e10 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * if an error oc
18e20 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
18e30 65 78 63 65 70 74 69 6f 6e 20 69 73 20 69 66 20  exception is if 
18e40 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
18e50 0a 2a 2a 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  .** to allocate 
18e60 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
18e70 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
18e80 65 63 74 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ect, a NULL will
18e90 0a 2a 2a 20 62 65 20 77 72 69 74 74 65 6e 20 69  .** be written i
18ea0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
18eb0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
18ec0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  o the [sqlite3] 
18ed0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 49 66 20 74 68  object..** If th
18ee0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
18ef0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
18f00 61 74 65 64 29 0a 2a 2a 20 73 75 63 63 65 73 73  ated).** success
18f10 66 75 6c 6c 79 2c 20 74 68 65 6e 20 5b 53 51 4c  fully, then [SQL
18f20 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
18f30 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
18f40 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
18f50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
18f60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
18f70 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
18f80 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
18f90 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62    routines can b
18fa0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
18fb0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
18fc0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
18fd0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
18fe0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
18ff0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
19000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
19010 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
19020 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
19030 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
19040 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63 61 6c  pen_v2()] is cal
19050 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
19060 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
19070 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 5b 73  byte order if [s
19080 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
19090 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
190a0 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
190b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
190c0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
190d0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
190e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
190f0 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  he [sqlite3*] ha
19100 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
19110 65 6c 65 61 73 65 64 20 62 79 20 70 61 73 73 69  eleased by passi
19120 6e 67 20 69 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ng it.** to [sql
19130 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
19140 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
19150 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
19160 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
19170 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
19180 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
19190 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
191a0 20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74   .** except that
191b0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
191c0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
191d0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
191e0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
191f0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
19200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19210 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
19220 61 6d 65 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a  ameter can be.**
19230 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c   one of:.**.** <
19240 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ol>.** <li>  [SQ
19250 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
19260 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  LY].** <li>  [SQ
19270 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
19280 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  ITE].** <li>  [S
19290 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
192a0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
192b0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20  OPEN_CREATE].** 
192c0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ol>.**.** The 
192d0 66 69 72 73 74 20 76 61 6c 75 65 20 6f 70 65 6e  first value open
192e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72  s the database r
192f0 65 61 64 2d 6f 6e 6c 79 2e 20 0a 2a 2a 20 49 66  ead-only. .** If
19300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
19310 65 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  es not previousl
19320 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
19330 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
19340 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70 74  * The second opt
19350 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68 65  ion opens.** the
19360 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
19370 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
19380 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
19390 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
193a0 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c 65  f.** if the file
193b0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
193c0 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72 20  ted.  In either 
193d0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
193e0 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65 61 64  e.** must alread
193f0 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65 72  y exist or an er
19400 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
19410 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69    The third opti
19420 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 74 68 65 20  on.** opens the 
19430 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
19440 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
19450 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74 20   and creates it 
19460 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
19470 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
19480 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70  .** The third op
19490 74 69 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f  tions is behavio
194a0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
194b0 20 75 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74   used for [sqlit
194c0 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  e3_open()].** an
194d0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
194e0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  6()]..**.** If t
194f0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
19500 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
19510 6e 5f 76 32 28 29 5d 20 69 73 20 6e 6f 74 20 6f  n_v2()] is not o
19520 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
19530 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
19540 61 62 6f 76 65 20 74 68 65 6e 20 74 68 65 20 62  above then the b
19550 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
19560 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
19570 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
19580 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
19590 61 6e 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e  an private.** in
195a0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
195b0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
195c0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
195d0 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a   This in-memory.
195e0 2a 2a 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ** database will
195f0 20 76 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65   vanish when the
19600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19610 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
19620 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
19630 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  on of SQLite mig
19640 68 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ht make use of a
19650 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
19660 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74  l filenames.** t
19670 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
19680 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
19690 2e 20 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  .  It is recomme
196a0 6e 64 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68  nded that .** wh
196b0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
196c0 6c 65 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f  lename really do
196d0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
196e0 20 22 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72   ":" that you pr
196f0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
19700 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
19710 65 20 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a  e like "./" to.*
19720 2a 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  * avoid ambiguit
19730 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
19740 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
19750 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
19760 6e 20 61 20 70 72 69 76 61 74 65 20 74 65 6d 70  n a private temp
19770 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
19780 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
19790 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73  e created.  This
197a0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
197b0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
197c0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
197d0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
197e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
197f0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
19800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
19810 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
19820 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19830 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
19840 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
19850 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
19860 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
19870 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a  rating system .*
19880 2a 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  * interface that
19890 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
198a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
198b0 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65  uld use.  If the
198c0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
198d0 65 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70  eter is a NULL p
198e0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
198f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
19900 5f 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  _vfs].** object 
19910 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
19920 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
19930 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
19940 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
19950 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
19960 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
19970 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
19980 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
19990 65 6e 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65  en_v2()] must be
199a0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
199b0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
199c0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
199d0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
199e0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
199f0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
19a00 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
19a10 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
19a20 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
19a30 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
19a40 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  * [sqlite3_open(
19a50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
19a60 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  pen_v2()]..**.**
19a70 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
19a80 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20  ** {F12701} The 
19a90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
19aa0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
19ab0 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
19ac0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
19ad0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
19ae0 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
19af0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
19b00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19b10 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
19b20 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
19b30 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
19b40 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
19b50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19b60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ..**.** {F12702}
19b70 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
19b80 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
19b90 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
19ba0 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
19bb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
19bc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
19bd0 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
19be0 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
19bf0 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
19c00 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
19c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19c20 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33  ]..**.** {F12703
19c30 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
19c40 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
19c50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
19c60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19c70 5d 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ], .**          
19c80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
19c90 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20  _v2()] writes a 
19ca0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77  pointer to a new
19cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
19cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19cd0 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a  n] into *ppDb..*
19ce0 2a 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68  *.** {F12704} Th
19cf0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
19d00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
19d10 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
19d20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
19d30 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
19d40 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53  rfaces return [S
19d50 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73  QLITE_OK] upon s
19d60 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20  uccess,.**      
19d70 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70      or an approp
19d80 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
19d90 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a  e] on failure..*
19da0 2a 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68  *.** {F12706} Th
19db0 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65  e default text e
19dc0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65  ncoding for a ne
19dd0 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  w database creat
19de0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
19df0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
19e00 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  en()] or [sqlite
19e10 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c  3_open_v2()] wil
19e20 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  l be UTF-8..**.*
19e30 2a 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64  * {F12707} The d
19e40 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f  efault text enco
19e50 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64  ding for a new d
19e60 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
19e70 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
19e80 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31    [sqlite3_open1
19e90 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46  6()] will be UTF
19ea0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  -16..**.** {F127
19eb0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
19ec0 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65  _open(F,D)] inte
19ed0 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
19ee0 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
19ef0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
19f00 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68  _v2(F,D,G,0)] wh
19f10 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65  ere the G parame
19f20 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
19f30 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f     [SQLITE_OPEN_
19f40 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49  READWRITE]|[SQLI
19f50 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
19f60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20  .**.** {F12711} 
19f70 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
19f80 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
19f90 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
19fa0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
19fb0 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
19fc0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
19fd0 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20  _READONLY] then 
19fe0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
19ff0 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
1a000 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f     for reading o
1a010 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  nly..**.** {F127
1a020 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  12} If the G par
1a030 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1a040 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1a050 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
1a060 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1a070 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1a080 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1a090 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1a0a0 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
1a0b0 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20          reading 
1a0c0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1a0d0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20  ossible, or for 
1a0e0 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20  reading only if 
1a0f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1a100 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1a110 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1a120 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1a130 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20  .**.** {F12713} 
1a140 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
1a150 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
1a160 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen(v2(F,D,G,V)]
1a170 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20   omits the.**   
1a180 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1a190 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1a1a0 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61  EATE] and the da
1a1b0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1a1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76  **          prev
1a1d0 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e  iously exist, an
1a1e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1a1f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ed..**.** {F1271
1a200 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  4} If the G para
1a210 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1a220 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c  3_open(v2(F,D,G,
1a230 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1a240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1a250 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1a260 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
1a270 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1a280 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
1a290 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
1a2a0 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65  st, then an atte
1a2b0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63  mpt is made to c
1a2c0 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20  reate and.**    
1a2d0 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65        initialize
1a2e0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a   the database..*
1a2f0 2a 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66  *.** {F12717} If
1a300 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
1a310 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1a320 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1a330 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
1a340 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
1a350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a360 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  )] is ":memory:"
1a370 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74  , then an privat
1a380 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
1a390 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d  phemeral, in-mem
1a3a0 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20  ory database is 
1a3b0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1a3c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20  connection..**  
1a3d0 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73          <todo>Is
1a3e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1a3f0 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ATE|SQLITE_OPEN_
1a400 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72  READWRITE requir
1a410 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
1a420 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  n sqlite3_open_v
1a430 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  2()?</todo>.**.*
1a440 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68  * {F12719} If th
1a450 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55  e filename is NU
1a460 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73  LL or an empty s
1a470 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1a480 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20  ivate,.**       
1a490 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d     ephemeral on-
1a4a0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1a4b0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a  ll be created..*
1a4c0 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1a4d0 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >Is SQLITE_OPEN_
1a4e0 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50  CREATE|SQLITE_OP
1a4f0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71  EN_READWRITE req
1a500 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  uired.**        
1a510 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65    in sqlite3_ope
1a520 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a  n_v2()?</todo>.*
1a530 2a 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68  *.** {F12721} Th
1a540 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1a550 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20  ection] created 
1a560 62 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  by .**          
1a570 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1a580 28 46 2c 44 2c 47 2c 56 29 5d 20 77 69 6c 6c 20  (F,D,G,V)] will 
1a590 75 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  use the.**      
1a5a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73      [sqlite3_vfs
1a5b0 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66  ] object identif
1a5c0 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72  ied by the V par
1a5d0 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 20 20  ameter, or.**   
1a5e0 20 20 20 20 20 20 20 74 68 65 20 64 65 66 61 75         the defau
1a5f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a600 20 6f 62 6a 65 63 74 20 69 73 20 56 20 69 73 20   object is V is 
1a610 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1a620 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 33 7d 20 54  **.** {F12723} T
1a630 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  wo [database con
1a640 6e 65 63 74 69 6f 6e 20 7c 20 64 61 74 61 62 61  nection | databa
1a650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
1a660 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d  will share a com
1a670 6d 6f 6e 20 63 61 63 68 65 0a 2a 2a 20 20 20 20  mon cache.**    
1a680 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 77 65        if both we
1a690 72 65 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74  re opened with t
1a6a0 68 65 20 73 61 6d 65 20 56 46 53 0a 2a 2a 20 20  he same VFS.**  
1a6b0 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
1a6c0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1a6d0 61 72 65 64 5f 63 61 63 68 65 20 7c 20 73 68 61  ared_cache | sha
1a6e0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 77  red cache mode w
1a6f0 61 73 20 65 6e 61 62 6c 65 64 5d 20 61 6e 64 0a  as enabled] and.
1a700 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62  **          if b
1a710 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f  oth filenames co
1a720 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e  mpare equal usin
1a730 67 20 6d 65 6d 63 6d 70 28 29 0a 2a 2a 20 20 20  g memcmp().**   
1a740 20 20 20 20 20 20 20 61 66 74 65 72 20 68 61 76         after hav
1a750 69 6e 67 20 62 65 65 6e 20 70 72 6f 63 65 73 73  ing been process
1a760 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1a770 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61  e3_vfs | xFullPa
1a780 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f  thname] method o
1a790 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
1a7a0 65 20 56 46 53 2e 0a 2a 2a 0a 2a 2f 0a 69 6e 74  e VFS..**.*/.int
1a7b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
1a7c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1a7d0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1a7e0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1a7f0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1a800 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1a810 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1a820 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1a830 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1a840 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
1a850 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
1a860 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1a870 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
1a880 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1a890 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1a8a0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1a8b0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1a8c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1a8d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1a8e0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1a8f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1a900 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1a910 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1a920 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1a930 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1a940 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1a950 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1a960 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1a970 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1a980 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1a990 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1a9a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a9b0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
1a9c0 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32  nd Messages {F12
1a9d0 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  800}.**.** The s
1a9e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1a9f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1aa00 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a  ns the numeric.*
1aa10 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
1aa20 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
1aa30 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
1aa40 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
1aa50 75 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72  ult code].** for
1aa60 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1aa70 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1aa80 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63  * API call assoc
1aa90 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73  iated.** with [s
1aaa0 71 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27  qlite3] handle '
1aab0 64 62 27 2e 20 49 66 20 61 20 70 72 69 6f 72 20  db'. If a prior 
1aac0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 20  API call failed 
1aad0 62 75 74 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20  but the.** most 
1aae0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1aaf0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1ab00 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1ab10 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1ab20 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ().** is undefin
1ab30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1ab40 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
1ab50 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
1ab60 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
1ab70 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
1ab80 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
1ab90 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
1aba0 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f  as either UTF8 o
1abb0 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69  r UTF16 respecti
1abc0 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
1abd0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1abe0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1abf0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1ac00 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1ac10 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1ac20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1ac30 79 20 77 69 74 68 20 66 72 65 65 69 6e 67 20 74  y with freeing t
1ac40 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1ac50 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1ac60 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1ac70 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1ac80 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1ac90 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1aca0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1acb0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1acc0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ctions..**.** IN
1acd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1ace0 7b 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71  {F12801} The [sq
1acf0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
1ad00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1ad10 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
1ad20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1ad30 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
1ad40 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  code] or.**     
1ad50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45       [SQLITE_IOE
1ad60 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
1ad70 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a  ed result code].
1ad80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
1ad90 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1ada0 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61  y failed interfa
1adb0 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  ce call associat
1adc0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
1add0 69 74 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ith [database co
1ade0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1adf0 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65 20  ** {F12803} The 
1ae00 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1ae10 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  D)] and [sqlite3
1ae20 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a  _errmsg16(D)].**
1ae30 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1ae40 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c  aces return Engl
1ae50 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
1ae60 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1ae70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ae80 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f   error in the mo
1ae90 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61  stly recently fa
1aea0 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1aeb0 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  all,.**         
1aec0 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68   encoded as eith
1aed0 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36  er UTF8 or UTF16
1aee0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1aef0 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d 20 54 68  *.** {F12807} Th
1af00 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1af10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
1af20 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71  rrmsg()] and [sq
1af30 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1af40 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
1af50 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
1af60 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e  e next SQLite in
1af70 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a  terface call..**
1af80 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61 6c  .** {F12808} Cal
1af90 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
1afa0 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
1afb0 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63  eturn an error c
1afc0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
1afd0 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
1afe0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
1aff0 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  ) do not.**     
1b000 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20       change the 
1b010 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65  error code or me
1b020 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62  ssage returned b
1b030 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1b040 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1b050 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1b060 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1b070 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1b080 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49  **.** {F12809} I
1b090 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
1b0a0 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65  re not associate
1b0b0 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  d with a specifi
1b0c0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  c.**          [d
1b0d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b0e0 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  on] (examples:.*
1b0f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1b100 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f  te3_mprintf()] o
1b110 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  r [sqlite3_enabl
1b120 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1b130 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f  ].**          do
1b140 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1b150 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1b160 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1b170 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1b180 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
1b190 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
1b1a0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
1b1b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b1c0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1b1d0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1b1e0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1b1f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1b200 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1b210 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1b220 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b230 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1b240 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30 30  nt Object {F1300
1b250 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
1b260 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1b270 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1b280 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1b290 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1b2a0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1b2b0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1b2c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b2d0 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 69  This.** object i
1b2e0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1b2f0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1b300 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1b310 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53   .** "compiled S
1b320 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
1b330 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
1b340 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a 2a  atement"..** .**
1b350 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1b360 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1b370 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1b380 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b390 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1b3a0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1b3b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1b3c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1b3d0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1b3e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1b3f0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1b400 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
1b410 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  s using.**      
1b420 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1b430 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
1b440 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d 2e  d_* interfaces].
1b450 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1b460 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1b470 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b480 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1b490 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1b4a0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1b4b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1b4c0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1b4d0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1b4e0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1b4f0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1b500 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1b510 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1b520 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b530 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1b540 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1b550 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1b560 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1b570 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1b580 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b590 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1b5a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1b5b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1b5c0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1b5d0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1b5e0 69 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31 32 37  ime Limits {F127
1b5f0 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  60}.**.** This i
1b600 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
1b610 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
1b620 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
1b630 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
1b640 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
1b650 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
1b660 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
1b670 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1b680 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1b690 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
1b6a0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
1b6b0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
1b6c0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1b6d0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
1b6e0 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
1b6f0 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
1b700 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
1b710 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
1b720 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
1b730 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
1b740 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
1b750 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
1b760 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20  hat construct.  
1b770 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  The function ret
1b780 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d  urns the old lim
1b790 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  it..**.** If the
1b7a0 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20   new limit is a 
1b7b0 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c  negative number,
1b7c0 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e   the limit is un
1b7d0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20  changed..** For 
1b7e0 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  the limit catego
1b7f0 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d  ry of SQLITE_LIM
1b800 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20  IT_XYZ there is 
1b810 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20  a hard upper.** 
1b820 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63  bound set by a c
1b830 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 2d 70 72  ompile-time C-pr
1b840 65 70 72 6f 63 65 73 73 20 6d 61 63 72 6f 20 6e  eprocess macro n
1b850 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f  amed SQLITE_MAX_
1b860 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  XYZ..** (The "_L
1b870 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1b880 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1b890 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74   "_MAX_".).** At
1b8a0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
1b8b0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
1b8c0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
1b8d0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
1b8e0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
1b8f0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
1b900 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52  r limit..**.** R
1b910 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un time limits a
1b920 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1b930 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1b940 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1b950 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1b960 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1b970 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1b980 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1b990 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1b9a0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1b9b0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1b9c0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1b9d0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1b9e0 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68  ** webbrowser th
1b9f0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1ba00 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1ba10 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1ba20 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1ba30 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1ba40 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1ba50 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1ba60 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1ba70 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1ba80 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1ba90 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1baa0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1bab0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1bac0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1bad0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1bae0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1baf0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1bb00 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1bb10 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1bb20 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1bb30 63 65 0a 2a 2a 20 61 74 74 61 63 68 2e 20 20 44  ce.** attach.  D
1bb40 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1bb50 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1bb60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1bb70 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1bb80 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1bb90 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1bba0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1bbb0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1bbc0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1bbd0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1bbe0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1bbf0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1bc00 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1bc10 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1bc20 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  A]..**.** This i
1bc30 6e 74 65 72 66 61 63 65 20 69 73 20 63 75 72 72  nterface is curr
1bc40 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
1bc50 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1bc60 64 20 69 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20  d is subject.** 
1bc70 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
1bc80 6f 76 61 6c 20 77 69 74 68 6f 75 74 20 70 72 69  oval without pri
1bc90 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a  or notice..**.**
1bca0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1bcb0 2a 2a 20 7b 46 31 32 37 36 32 7d 20 41 20 73 75  ** {F12762} A su
1bcc0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1bcd0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1bce0 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
1bcf0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  is.**          p
1bd00 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20  ositive changes 
1bd10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1bd20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1bd30 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1bd40 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   in [database co
1bd50 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
1bd60 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6c          to the l
1bd70 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74  esser of V and t
1bd80 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
1bd90 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 0a  und on the size.
1bda0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 43  **          of C
1bdb0 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20   that is set at 
1bdc0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a  compile-time..**
1bdd0 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41 20 73  .** {F12766} A s
1bde0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1bdf0 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1be00 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1be10 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
1be20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20           leaves 
1be30 74 68 65 20 73 74 61 74 65 20 6f 66 20 5b 64 61  the state of [da
1be40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1be50 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
1be60 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41  **.** {F12769} A
1be70 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1be80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1be90 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
1bea0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1beb0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
1bec0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1bed0 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1bee0 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
1bef0 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  in [database con
1bf00 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74  nection] D as it
1bf10 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68   was prior to th
1bf20 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  e call..*/.int s
1bf30 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1bf40 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1bf50 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1bf60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1bf70 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1bf80 67 6f 72 69 65 73 20 7b 46 31 32 37 39 30 7d 0a  gories {F12790}.
1bf90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
1bfa0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c  mit category} {l
1bfb0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1bfc0 0a 2a 2a 20 0a 2a 2a 20 54 68 65 73 65 20 63 6f  .** .** These co
1bfd0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1bfe0 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f  arious aspects o
1bff0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
1c000 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
1c010 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64  t can be limited
1c020 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c   in size by call
1c030 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  s to [sqlite3_li
1c040 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d  mit()]..** The m
1c050 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1c060 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72  arious limits ar
1c070 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
1c080 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1c090 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c0a0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1c0b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1c0c0 20 6f 66 20 61 6e 79 0a 2a 2a 20 73 74 72 69 6e   of any.** strin
1c0d0 67 20 6f 72 20 62 6c 6f 62 20 6f 72 20 74 61 62  g or blob or tab
1c0e0 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a  le row.<dd>.**.*
1c0f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1c100 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
1c110 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c120 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1c130 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c140 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1c150 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1c160 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1c170 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c180 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1c190 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1c1a0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1c1b0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1c1c0 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20  a SELECT or the 
1c1d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c1e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
1c1f0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
1c200 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
1c210 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
1c220 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c230 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1c240 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1c250 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1c260 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
1c270 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
1c280 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  ression.</dd>.**
1c290 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c2a0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1c2b0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
1c2c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c2d0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
1c2e0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
1c2f0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
1c300 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1c310 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1c320 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c330 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c340 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
1c350 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
1c360 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
1c370 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1c380 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
1c390 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
1c3a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c3b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
1c3c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c3d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1c3e0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
1c3f0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  nction.</dd>.**.
1c400 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c410 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
1c420 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c430 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1c440 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1c450 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
1c460 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
1c470 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1c480 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1c490 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1c4a0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
1c4b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1c4c0 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42   LIKE or.** GLOB
1c4d0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
1c4e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c4f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1c500 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
1c510 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c520 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62  number of variab
1c530 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  les in an SQL st
1c540 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e  atement that can
1c550 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64  .** be bound.</d
1c560 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  d>.** </dl>.*/.#
1c570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c580 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
1c590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
1c5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c5b0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
1c5c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1c5d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c5e0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
1c5f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c600 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
1c610 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1c620 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1c630 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
1c640 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1c650 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1c660 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
1c670 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1c680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c690 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
1c6a0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1c6b0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
1c6c0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
1c6d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
1c6e0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
1c6f0 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
1c700 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1c710 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
1c720 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
1c730 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1c740 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
1c750 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20         9../*.** 
1c760 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1c770 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
1c780 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a  ment {F13010}.**
1c790 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
1c7a0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
1c7b0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
1c7c0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
1c7d0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
1c7e0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
1c7f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20  these routines. 
1c800 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
1c810 20 61 72 67 75 6d 65 6e 74 20 22 64 62 22 20 69   argument "db" i
1c820 73 20 61 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s an [database c
1c830 6f 6e 6e 65 63 74 69 6f 6e 5d 20 0a 2a 2a 20 6f  onnection] .** o
1c840 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1c850 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71  rior call to [sq
1c860 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1c870 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c880 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
1c890 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 0a 2a 2a  3_open16()]. .**
1c8a0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1c8b0 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74  ment "zSql" is t
1c8c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
1c8d0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
1c8e0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
1c8f0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1c900 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
1c910 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
1c920 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c930 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
1c940 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20   uses UTF-8 and 
1c950 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1c960 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
1c970 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
1c980 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45  * use UTF-16. {E
1c990 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ND}.**.** If the
1c9a0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1c9b0 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  is less.** than 
1c9c0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1c9d0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1c9e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1c9f0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 6e  minator..** If n
1ca00 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1ca10 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
1ca20 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1ca30 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74 65 73  ber of .** bytes
1ca40 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1ca50 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20    When nByte is 
1ca60 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1ca70 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1ca80 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1ca90 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1caa0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1cab0 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20 74 68  racter or .** th
1cac0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
1cad0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
1cae0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
1caf0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
1cb00 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
1cb10 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
1cb20 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
1cb30 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
1cb40 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
1cb50 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
1cb60 68 61 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  had by passing a
1cb70 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
1cb80 72 20 74 68 61 74 20 0a 2a 2a 20 69 73 20 65 71  r that .** is eq
1cb90 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1cba0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1cbb0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1cbc0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 20  i>including</i> 
1cbd0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1cbe0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 7b 45 4e  inator bytes.{EN
1cbf0 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c  D}.**.** *pzTail
1cc00 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1cc10 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
1cc20 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64  yte past the end
1cc30 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1cc40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1cc50 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
1cc60 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d  outines only com
1cc70 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a  pile the first.*
1cc80 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  * statement in z
1cc90 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
1cca0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1ccb0 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73   to what remains
1ccc0 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  .** uncompiled..
1ccd0 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73  **.** *ppStmt is
1cce0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1ccf0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1cd00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cd10 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1cd20 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1cd30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cd40 2e 20 20 4f 72 20 69 66 20 74 68 65 72 65 20 69  .  Or if there i
1cd50 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1cd60 74 6d 74 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f  tmt is.** set to
1cd70 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
1cd80 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1cd90 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1cda0 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61 6e  e input.** is an
1cdb0 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  d empty string o
1cdc0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1cdd0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1cde0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31   to NULL..** {U1
1cdf0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
1ce00 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1ce10 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1ce20 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20 63  eleting the.** c
1ce30 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1ce40 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  ement.** using [
1ce50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1ce60 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1ce70 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1ce80 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
1ce90 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
1cea0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1ceb0 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20  therwise an .** 
1cec0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1ced0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1cee0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1cef0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1cf00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1cf10 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1cf20 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1cf30 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1cf40 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1cf50 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1cf60 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1cf70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1cf80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1cf90 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1cfa0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
1cfb0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
1cfc0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
1cfd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
1cfe0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
1cff0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
1d000 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
1d010 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
1d020 20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61   the .** origina
1d030 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b 45 4e 44  l SQL text. {END
1d040 7d 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  } This causes th
1d050 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1d060 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1d070 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66  ** behave a diff
1d080 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77  erently in two w
1d090 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1d0a0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68  ** <li>.** If th
1d0b0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
1d0c0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
1d0d0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
1d0e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d0f0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
1d100 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
1d110 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1d120 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
1d130 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
1d140 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
1d150 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
1d160 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20   again.  If the 
1d170 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67  schema has chang
1d180 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74  ed in.** a way t
1d190 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74  hat makes the st
1d1a0 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65  atement no longe
1d1b0 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65  r valid, [sqlite
1d1c0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73  3_step()] will s
1d1d0 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  till.** return [
1d1e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20  SQLITE_SCHEMA]. 
1d1f0 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20   But unlike the 
1d200 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c  legacy behavior,
1d210 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48   .** [SQLITE_SCH
1d220 45 4d 41 5d 20 69 73 20 6e 6f 77 20 61 20 66 61  EMA] is now a fa
1d230 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1d240 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1d250 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1d260 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1d270 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1d280 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1d290 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1d2a0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1d2b0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1d2c0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1d2d0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1d2e0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1d2f0 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a  ] return. {END}.
1d300 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1d310 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65  li>.** When an e
1d320 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a  rror occurs, .**
1d330 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d340 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1d350 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1d360 64 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  d .** [error cod
1d370 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1d380 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 0a   error codes]. .
1d390 2a 2a 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  ** The legacy be
1d3a0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 20  havior was that 
1d3b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d3c0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
1d3d0 72 6e 20 61 20 67 65 6e 65 72 69 63 0a 2a 2a 20  rn a generic.** 
1d3e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1d3f0 65 73 75 6c 74 20 63 6f 64 65 20 61 6e 64 20 79  esult code and y
1d400 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
1d410 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
1d420 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
1d430 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
1d440 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
1d450 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
1d460 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
1d470 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
1d480 32 22 20 70 72 65 70 61 72 65 20 69 6e 74 65 72  2" prepare inter
1d490 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
1d4a0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
1d4b0 20 74 68 65 20 65 72 72 6f 72 20 69 73 0a 2a 2a   the error is.**
1d4c0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1d4d0 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1d4e0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
1d4f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1d500 20 7b 46 31 33 30 31 31 7d 20 54 68 65 20 5b 73   {F13011} The [s
1d510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
1d520 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64  b,zSql,...)] and
1d530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1d540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d550 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
1d560 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
1d570 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
1d580 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
1d590 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
1d5a0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   as UTF-8..**.**
1d5b0 20 7b 46 31 33 30 31 32 7d 20 54 68 65 20 5b 73   {F13012} The [s
1d5c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d5d0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
1d5e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1d5f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d600 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  6_v2(db,zSql,...
1d610 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
1d620 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
1d630 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
1d640 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
1d650 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69  eter as UTF-16 i
1d660 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1d670 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
1d680 46 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e  F13013} If the n
1d690 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1d6a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d6b0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1d6c0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1d6d0 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1d6e0 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68  iants is less th
1d6f0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 53 51  an zero, then SQ
1d700 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20  L text is.**    
1d710 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20        read from 
1d720 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1d730 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1d740 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1d750 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20  .** {F13014} If 
1d760 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1d770 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
1d780 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1d790 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a  l,nByte,...)].**
1d7a0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74            and it
1d7b0 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f  s variants is no
1d7c0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1d7d0 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20   at most nBytes 
1d7e0 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
1d7f0 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65    SQL text is re
1d800 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a  ad from zSql..**
1d810 0a 2a 2a 20 7b 46 31 33 30 31 35 7d 20 49 6e 20  .** {F13015} In 
1d820 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d830 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c  _v2(db,zSql,N,P,
1d840 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73  pzTail)] and its
1d850 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20   variants.**    
1d860 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71        if the zSq
1d870 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  l input text con
1d880 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20  tains more than 
1d890 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  one SQL statemen
1d8a0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  t.**          an
1d8b0 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  d pzTail is not 
1d8c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61  NULL, then *pzTa
1d8d0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
1d8e0 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  int to the.**   
1d8f0 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74         first byt
1d900 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
1d910 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
1d920 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1d930 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  l..**          <
1d940 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a  todo>What does *
1d950 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20  pzTail point to 
1d960 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20  if there is one 
1d970 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f  statement?</todo
1d980 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d  >.**.** {F13016}
1d990 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1d9a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
1d9b0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1d9c0 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d  l,N,ppStmt,...)]
1d9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1d9e0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
1d9f0 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20  nts writes into 
1da00 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65  *ppStmt a pointe
1da10 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20  r to a new.**   
1da20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1da30 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61   statement] or a
1da40 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c   pointer to NULL
1da50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
1da60 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  zSql contains no
1da70 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
1da80 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63   whitespace or c
1da90 6f 6d 6d 65 6e 74 73 2e 20 0a 2a 2a 0a 2a 2a 20  omments. .**.** 
1daa0 7b 46 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {F13019} The [sq
1dab0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dac0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
1dad0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
1dae0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1daf0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
1db00 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
1db10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
1db20 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1db30 20 7b 46 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {F13021} Before
1db40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1db50 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
1db60 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
1db70 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
1db80 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
1db90 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
1dba0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1dbb0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 0a  an [SQLITE_OK]).
1dbc0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20 66  **          it f
1dbd0 69 72 73 74 20 73 65 74 73 20 2a 70 70 53 74 6d  irst sets *ppStm
1dbe0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
1dbf0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1dc00 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1dc10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1dc20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1dc30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1dc40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1dc50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1dc60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1dc70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1dc80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1dc90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1dca0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1dcb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1dcc0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1dcd0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1dce0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1dcf0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1dd00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1dd10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1dd20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1dd30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1dd40 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1dd50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1dd60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1dd70 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1dd80 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1dd90 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1dda0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1ddb0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1ddc0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1ddd0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1dde0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1ddf0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1de00 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1de10 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1de20 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1de30 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1de40 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1de50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1de60 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1de70 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1de80 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1de90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1dea0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1deb0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1dec0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1ded0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1dee0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1def0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1df00 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1df10 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1df20 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1df30 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1df40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1df50 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1df60 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1df70 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1df80 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1df90 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1dfa0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1dfb0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1dfc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dfd0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1dfe0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1dff0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1e000 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1e010 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1e020 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1e030 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1e040 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e050 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e060 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e070 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e080 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e090 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e0a0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e0b0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e0c0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1e0d0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e0e0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e0f0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e100 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1e110 49 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  IREF: Retrieving
1e120 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1e130 46 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13100}.**.** Th
1e140 69 73 20 69 6e 74 65 72 66 61 63 65 20 20 63 61  is interface  ca
1e150 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
1e160 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
1e170 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
1e180 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
1e190 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
1e1a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e1b0 65 6e 74 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ent]..**.** INVA
1e1c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1e1d0 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
1e1e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e1f0 74 5d 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a  t] passed as .**
1e200 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 6e            the an
1e210 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1e220 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
1e230 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20   compiled.**    
1e240 20 20 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75        compiled u
1e250 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1e260 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e270 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1e280 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1e290 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 20  re16_v2()],.**  
1e2a0 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
1e2b0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 66 75 6e  lite3_sql()] fun
1e2c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1e2d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
1e2e0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1e2f0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
1e300 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
1e310 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
1e320 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1e330 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
1e340 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tement..**.** {F
1e350 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
1e360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e370 74 5d 20 70 61 73 73 65 64 20 61 73 20 0a 2a 2a  t] passed as .**
1e380 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 6e            the an
1e390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1e3a0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
1e3b0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 20 20 20   compiled.**    
1e3c0 20 20 20 20 20 20 63 6f 6d 70 69 6c 65 64 20 75        compiled u
1e3d0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1e3e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e3f0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1e400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e410 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1e420 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
1e430 73 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  sql()] function 
1e440 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1e450 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
1e460 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
1e470 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
1e480 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69  qlite3_sql(S)] i
1e490 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
1e4a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1e4b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e4c0 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20  t] S is deleted 
1e4d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1e4e0 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a  inalize(S)]..*/.
1e4f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1e500 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
1e510 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1e520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1e530 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
1e540 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 20  d Value Object  
1e550 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F15000}.** KEYW
1e560 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
1e570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
1e580 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
1e590 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
1e5a0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
1e5b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1e5c0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
1e5d0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
1e5e0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
1e5f0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
1e600 73 65 20 74 61 62 6c 65 2e 0a 2a 2a 20 53 51 4c  se table..** SQL
1e610 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1e620 20 74 79 70 69 6e 67 20 66 6f 72 20 74 68 65 20   typing for the 
1e630 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
1e640 2e 20 20 0a 2a 2a 20 56 61 6c 75 65 73 20 73 74  .  .** Values st
1e650 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
1e660 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 63 61  value objects ca
1e670 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e 74 65 67  n be.** be integ
1e680 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
1e690 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
1e6a0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
1e6b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
1e6c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e6d0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
1e6e0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
1e6f0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
1e700 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
1e710 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
1e720 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e730 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
1e740 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
1e750 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
1e760 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
1e770 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1e780 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
1e790 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
1e7a0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
1e7b0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
1e7c0 73 20 73 70 65 63 69 66 69 65 73 20 0a 2a 2a 20  s specifies .** 
1e7d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1e7e0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1e7f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e800 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1e810 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1e820 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1e830 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1e840 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1e850 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1e860 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1e870 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1e880 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e890 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e8a0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1e8b0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1e8c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e8d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e8e0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1e8f0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1e900 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1e910 2a 2a 20 28 77 69 74 68 20 53 51 4c 49 54 45 5f  ** (with SQLITE_
1e920 54 48 52 45 41 44 53 41 46 45 3d 30 20 61 6e 64  THREADSAFE=0 and
1e930 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
1e940 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
1e950 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 74 68 65  urning 0).** the
1e960 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1e970 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1e980 6e 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 61  n.** protected a
1e990 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  nd unprotected s
1e9a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e9b0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1e9c0 6e 20 62 65 0a 2a 2a 20 75 73 65 64 20 69 6e 74  n be.** used int
1e9d0 65 72 63 68 61 6e 67 65 61 62 6c 65 2e 20 20 48  erchangeable.  H
1e9e0 6f 77 65 76 65 72 2c 20 66 6f 72 20 6d 61 78 69  owever, for maxi
1e9f0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
1ea00 6c 69 74 79 20 69 74 0a 2a 2a 20 69 73 20 72 65  lity it.** is re
1ea10 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
1ea20 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 61 6b 65  pplications make
1ea30 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
1ea40 20 62 65 74 77 65 65 6e 0a 2a 2a 20 62 65 74 77   between.** betw
1ea50 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
1ea60 64 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  d unprotected sq
1ea70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ea80 63 74 73 20 65 76 65 6e 20 69 66 0a 2a 2a 20 74  cts even if.** t
1ea90 68 65 79 20 61 72 65 20 73 69 6e 67 6c 65 20 74  hey are single t
1eaa0 68 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  hreaded..**.** T
1eab0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1eac0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
1ead0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
1eae0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
1eaf0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1eb00 6e 20 6f 66 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  n of .** [sqlite
1eb10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1eb20 6e 20 7c 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  n | application-
1eb30 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1eb40 74 69 6f 6e 73 5d 0a 2a 2a 20 61 72 65 20 70 72  tions].** are pr
1eb50 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20  otected..** The 
1eb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1eb70 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
1eb80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
1eb90 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
1eba0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
1ebb0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
1ebc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ebd0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
1ebe0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
1ebf0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
1ec00 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ec10 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 20  _bind_value()]. 
1ec20 20 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65   .** The [sqlite
1ec30 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
1ec40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
1ec50 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
1ec60 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
1ec70 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
1ec80 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ec90 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
1eca0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
1ecb0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
1ecc0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 51 4c  * CAPI3REF:  SQL
1ecd0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
1ece0 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30 30 31  t Object {F16001
1ecf0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  }.**.** The cont
1ed00 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1ed10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1ed20 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1ed30 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1ed40 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1ed50 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
1ed60 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1ed70 74 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73 20 61  t.** object is a
1ed80 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1ed90 6d 65 74 65 72 20 74 6f 20 0a 2a 2a 20 5b 73 71  meter to .** [sq
1eda0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1edb0 63 74 69 6f 6e 20 7c 20 61 70 70 6c 69 63 61 74  ction | applicat
1edc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1edd0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1ede0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 65 64  he applicationed
1edf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1ee00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1ee10 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1ee20 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1ee30 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1ee40 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1ee50 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
1ee60 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
1ee70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
1ee80 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
1ee90 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75  ],.** [sqlite3_u
1eea0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
1eeb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1eec0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 0a 2a  _db_handle()],.*
1eed0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  * [sqlite3_get_a
1eee0 75 78 64 61 74 61 28 29 5d 2c 20 61 6e 64 2f 6f  uxdata()], and/o
1eef0 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
1ef00 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
1ef10 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1ef20 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1ef30 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1ef40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
1ef50 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1ef60 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1ef70 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a  ments {F13500}.*
1ef80 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20  *.** In the SQL 
1ef90 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f  strings input to
1efa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1efb0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 0a  e_v2()] and its.
1efc0 2a 2a 20 76 61 72 69 61 6e 74 73 2c 20 6c 69 74  ** variants, lit
1efd0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1efe0 6c 61 63 65 20 62 79 20 61 20 70 61 72 61 6d 65  lace by a parame
1eff0 74 65 72 20 69 6e 20 6f 6e 65 0a 2a 2a 20 6f 66  ter in one.** of
1f000 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a   these forms:.**
1f010 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
1f020 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
1f030 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
1f040 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
1f050 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
1f060 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
1f070 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d  e parameter form
1f080 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e  s shown above NN
1f090 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  N is an integer 
1f0a0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 56 56 56 20  literal,.** VVV 
1f0b0 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
1f0c0 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 0a 2a 2a  rameter name..**
1f0d0 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74   The values of t
1f0e0 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20  hese parameters 
1f0f0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
1f100 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1f110 65 73 22 0a 2a 2a 20 6f 72 20 22 53 51 4c 20 70  es".** or "SQL p
1f120 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1f130 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1f140 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f150 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1f160 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1f170 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1f180 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1f190 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f1a0 74 69 6e 65 73 20 61 6c 77 61 79 73 0a 2a 2a 20  tines always.** 
1f1b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1f1c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1f1d0 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1f1e0 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1f1f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f200 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1f210 73 2e 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  s. The second.**
1f220 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1f230 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61   index of the pa
1f240 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
1f250 74 2e 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20  t. The.** first 
1f260 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1f270 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
1f280 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1f290 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
1f2a0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
1f2b0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
1f2c0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
1f2d0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
1f2e0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
1f2f0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
1f300 75 72 72 65 6e 63 65 2e 20 0a 2a 2a 20 54 68 65  urrence. .** The
1f310 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1f320 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1f330 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1f340 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1f350 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f360 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66  r_name()] API if
1f370 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69   desired.  The i
1f380 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
1f390 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
1f3a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
1f3b0 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61  N..** The NNN va
1f3c0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
1f3d0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f  een 1 and the co
1f3e0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61  mpile-time.** pa
1f3f0 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d  rameter SQLITE_M
1f400 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1f410 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  ER (default valu
1f420 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54  e: 999)..**.** T
1f430 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1f440 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
1f450 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
1f460 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
1f470 6e 20 74 68 6f 73 65 0a 2a 2a 20 72 6f 75 74 69  n those.** routi
1f480 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1f490 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1f4a0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1f4b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1f4c0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 70 61 72 61  s.** in the para
1f4d0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1f4e0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1f4f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1f500 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 0a 2a 2a 20  <u>bytes</u>.** 
1f510 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1f520 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1f530 63 68 61 72 61 63 74 65 72 73 2e 20 0a 2a 2a 20  characters. .** 
1f540 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1f550 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
1f560 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
1f570 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
1f580 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1f590 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
1f5a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1f5b0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
1f5c0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1f5d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
1f5e0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
1f5f0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
1f600 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
1f610 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
1f620 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
1f630 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
1f640 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
1f650 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
1f660 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
1f670 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66  ith it. If the f
1f680 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
1f690 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
1f6a0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
1f6b0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
1f6c0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
1f6d0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
1f6e0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
1f6f0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
1f700 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
1f710 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
1f720 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20  ** If the fifth 
1f730 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1f740 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1f750 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1f760 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1f770 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1f780 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1f790 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1f7a0 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1f7b0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f7c0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1f7d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1f7e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
1f7f0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
1f800 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
1f810 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
1f820 65 64 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  ed with zeros.  
1f830 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1f840 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1f850 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1f860 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1f870 68 6f 6c 64 20 69 74 20 73 69 7a 65 29 20 77 68  hold it size) wh
1f880 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
1f890 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
1f8a0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
1f8b0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
1f8c0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
1f8d0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
1f8e0 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
1f8f0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 20  r written using 
1f900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1f910 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1f920 6e 74 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  nt BLOB I/O] rou
1f930 74 69 6e 65 73 2e 20 41 20 6e 65 67 61 74 69 76  tines. A negativ
1f940 65 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 20 74  e.** value for t
1f950 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1f960 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1f970 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1f980 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
1f990 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
1f9a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
1f9b0 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
1f9c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
1f9d0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
1f9e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
1f9f0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
1fa00 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
1fa10 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
1fa20 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1fa30 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1fa40 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1fa50 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
1fa60 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
1fa70 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
1fa80 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
1fa90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1faa0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1fab0 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
1fac0 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
1fad0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
1fae0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
1faf0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1fb00 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1fb10 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1fb20 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
1fb30 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
1fb40 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
1fb50 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
1fb60 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74  TE_MISUSE] might
1fb70 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
1fb80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
1fb90 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a  re called on a.*
1fba0 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  * virtual machin
1fbb0 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72  e that is the wr
1fbc0 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69  ong state or whi
1fbd0 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ch has already b
1fbe0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a  een finalized..*
1fbf0 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d  * Detection of m
1fc00 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61  isuse is unrelia
1fc10 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ble.  Applicatio
1fc20 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ns should not de
1fc30 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54  pend.** on SQLIT
1fc40 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73  E_MISUSE returns
1fc50 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  .  SQLITE_MISUSE
1fc60 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
1fc70 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20  indicate a.** a 
1fc80 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74  logic error in t
1fc90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1fca0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1fcb0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1fcc0 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72  .** panic rather
1fcd0 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c   than return SQL
1fce0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a  ITE_MISUSE..**.*
1fcf0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1fd00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1fd10 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
1fd20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1fd30 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1fd40 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1fd50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fd60 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1fd70 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1fd80 2a 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20  ** {F13506} The 
1fd90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fda0 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   | SQL statement
1fdb0 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67   compiler] recog
1fdc0 6e 69 7a 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  nizes.**        
1fdd0 20 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20    tokens of the 
1fde0 66 6f 72 6d 73 20 22 3f 22 2c 20 22 3f 4e 4e 4e  forms "?", "?NNN
1fdf0 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56  ", "$VVV", ":VVV
1fe00 22 2c 20 61 6e 64 20 22 40 56 56 56 22 0a 2a 2a  ", and "@VVV".**
1fe10 20 20 20 20 20 20 20 20 20 20 61 73 20 53 51 4c            as SQL
1fe20 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77 68 65   parameters, whe
1fe30 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65  re NNN is any se
1fe40 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
1fe50 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
1fe60 20 20 64 69 67 69 74 73 20 61 6e 64 20 77 68 65    digits and whe
1fe70 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65  re VVV is any se
1fe80 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
1fe90 20 6d 6f 72 65 20 0a 2a 2a 20 20 20 20 20 20 20   more .**       
1fea0 20 20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20     alphanumeric 
1feb0 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a  characters or ":
1fec0 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f  :" optionally fo
1fed0 6c 6c 6f 77 65 64 20 62 79 0a 2a 2a 20 20 20 20  llowed by.**    
1fee0 20 20 20 20 20 20 61 20 73 74 72 69 6e 67 20 63        a string c
1fef0 6f 6e 74 61 69 6e 69 6e 67 20 6e 6f 20 73 70 61  ontaining no spa
1ff00 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65  ces and containe
1ff10 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68  d within parenth
1ff20 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eses..**.** {F13
1ff30 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c  509} The initial
1ff40 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
1ff50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
1ff60 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31  LL..**.** {F1351
1ff70 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  2} The index of 
1ff80 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d  an "?" SQL param
1ff90 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67  eter is one larg
1ffa0 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20  er than the.**  
1ffb0 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20          largest 
1ffc0 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
1ffd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65  ameter to the le
1ffe0 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20  ft, or 1 if.**  
1fff0 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20          the "?" 
20000 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20  is the leftmost 
20010 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  SQL parameter..*
20020 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20 54 68  *.** {F13515} Th
20030 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
20040 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74  NNN" SQL paramet
20050 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65  er is the intege
20060 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  r NNN..**.** {F1
20070 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20  3518} The index 
20080 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24  of an ":VVV", "$
20090 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20  VVV", or "@VVV" 
200a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
200b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
200c0 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64   same as the ind
200d0 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f  ex of leftmost o
200e0 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68  ccurrences of th
200f0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
20100 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72     parameter, or
20110 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74   one more than t
20120 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
20130 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20   over all.**    
20140 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
20150 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20   to the left if 
20160 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73  this is the firs
20170 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20  t occurrence.** 
20180 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73           of this
20190 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31   parameter, or 1
201a0 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
201b0 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74  leftmost paramet
201c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32  er..**.** {F1352
201d0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
201e0 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20 73 74  prepare | SQL st
201f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
20200 5d 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20  ] fail with.**  
20210 20 20 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49          an [SQLI
20220 54 45 5f 52 41 4e 47 45 5d 20 65 72 72 6f 72 20  TE_RANGE] error 
20230 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  if the index of 
20240 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
20250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
20260 6c 65 73 73 20 74 68 61 6e 20 31 20 6f 72 20 67  less than 1 or g
20270 72 65 61 74 65 72 20 74 68 61 6e 20 53 51 4c 49  reater than SQLI
20280 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
20290 4e 55 4d 42 45 52 2e 0a 2a 2a 0a 2a 2a 20 7b 46  NUMBER..**.** {F
202a0 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20  13524} Calls to 
202b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
202c0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
202d0 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a  d(S,N,V,...)].**
202e0 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
202f0 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20  ate the value V 
20300 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72  with all SQL par
20310 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61  ameters having a
20320 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
20330 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20  dex of N in the 
20340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20350 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
20360 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20  13527} Calls to 
20370 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
20380 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
20390 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  d(S,N,...)].**  
203a0 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65          override
203b0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
203c0 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
203d0 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a  s of S and N..**
203e0 0a 2a 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e  .** {F13530} Bin
203f0 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65  dings establishe
20400 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69  d by [sqlite3_bi
20410 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
20420 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a  3_bind(S,...)].*
20430 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69  *          persi
20440 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  st across calls 
20450 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
20460 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  t(S)]..**.** {F1
20470 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3533} In calls t
20480 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
20490 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
204a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
204b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
204c0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
204d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
204e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
204f0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
20500 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66  Lite binds the f
20510 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20  irst L.**       
20520 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20     bytes of the 
20530 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20 70  blob or string p
20540 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20  ointed to by V, 
20550 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20  when L.**       
20560 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69     is non-negati
20570 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33  ve..**.** {F1353
20580 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  6} In calls to [
20590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
205a0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72  t(S,N,V,L,D)] or
205b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
205c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
205d0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
205e0 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61  Lite binds chara
205f0 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  cters.**        
20600 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68    from V through
20610 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
20620 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c  character when L
20630 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
20640 0a 2a 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20  .** {F13539} In 
20650 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20660 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
20670 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
20680 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20690 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
206a0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
206b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
206c0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
206d0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
206e0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
206f0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
20700 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
20710 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
20720 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56  that the value V
20730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
20740 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75  held in static u
20750 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74  nmanaged space t
20760 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61  hat will not cha
20770 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
20780 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
20790 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69  ime of the bindi
207a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34  ng..**.** {F1354
207b0 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  2} In calls to [
207c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
207d0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
207e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
207f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
20800 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
20810 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20820 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
20830 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
20840 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
20850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
20860 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52  stant [SQLITE_TR
20870 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f  ANSIENT], the ro
20880 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 20 0a 2a  utine makes a .*
20890 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61  *          priva
208a0 74 65 20 63 6f 70 79 20 6f 66 20 56 20 76 61 6c  te copy of V val
208b0 75 65 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  ue before it ret
208c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  urns..**.** {F13
208d0 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  545} In calls to
208e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
208f0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
20900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
20910 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
20920 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
20930 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
20940 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
20950 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
20960 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72  n D is a pointer
20970 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
20980 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  a function, SQLi
20990 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20  te invokes that 
209a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74  function to dest
209b0 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  roy the.**      
209c0 20 20 20 20 56 20 76 61 6c 75 65 20 61 66 74 65      V value afte
209d0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
209e0 64 20 75 73 69 6e 67 20 74 68 65 20 56 20 76 61  d using the V va
209f0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35  lue..**.** {F135
20a00 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  48} In calls to 
20a10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
20a20 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d  roblob(S,N,V,L)]
20a30 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64   the value bound
20a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
20a50 61 20 62 6c 6f 62 20 6f 66 20 4c 20 62 79 74 65  a blob of L byte
20a60 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  s, or a zero-len
20a70 67 74 68 20 62 6c 6f 62 20 69 66 20 4c 20 69 73  gth blob if L is
20a80 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   negative..**.**
20a90 20 7b 46 31 33 35 35 31 7d 20 49 6e 20 63 61 6c   {F13551} In cal
20aa0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
20ab0 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29  ind_value(S,N,V)
20ac0 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74  ] the V argument
20ad0 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   may.**         
20ae0 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70 72   be either a [pr
20af0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20b00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72  value] object or
20b10 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
20b20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
20b30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
20b40 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ct..*/.int sqlit
20b50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
20b60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20b70 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
20b80 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
20b90 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
20ba0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
20bb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20bc0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
20bd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
20be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20bf0 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
20c00 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
20c10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20c20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
20c30 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
20c40 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
20c50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
20c60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20c70 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
20c80 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
20c90 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
20ca0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
20cb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20cc0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
20cd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
20ce0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
20cf0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
20d00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
20d10 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
20d20 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
20d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
20d40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20d50 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
20d60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
20d70 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
20d80 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
20d90 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20   SQL Parameters 
20da0 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13600}.**.** T
20db0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
20dc0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
20dd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 53 51  the number of SQ
20de0 4c 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L parameters.** 
20df0 69 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  in a prepared st
20e00 61 74 65 6d 65 6e 74 2e 20 20 53 51 4c 20 70 61  atement.  SQL pa
20e10 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
20e20 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
20e30 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
20e40 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
20e50 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
20e60 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
20e70 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
20e80 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
20e90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
20ea0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
20eb0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
20ec0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
20ed0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
20ee0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
20ef0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
20f00 68 65 20 6c 61 72 67 65 73 74 20 70 61 72 61 6d  he largest param
20f10 65 74 65 72 2e 0a 2a 2a 20 46 6f 72 20 61 6c 6c  eter..** For all
20f20 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
20f30 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
20f40 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 20  rrespond to the 
20f50 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 75 6e 69  number of.** uni
20f60 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
20f70 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
20f80 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
20f90 73 65 64 2c 20 74 68 65 72 65 20 6d 61 79 0a 2a  sed, there may.*
20fa0 2a 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  * be gaps in the
20fb0 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
20fc0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
20fd0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
20fe0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
20ff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21000 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
21010 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
21020 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21030 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
21040 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21050 7b 46 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71  {F13601} The [sq
21060 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21070 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69  eter_count(S)] i
21080 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
21090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
210a0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
210b0 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
210c0 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ters in the.**  
210d0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
210e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20  d statement] S, 
210f0 6f 72 20 30 20 69 66 20 53 0a 2a 2a 20 20 20 20  or 0 if S.**    
21100 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 73 20 6e        contains n
21110 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  o SQL parameters
21120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21130 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21140 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
21150 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
21160 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
21170 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
21180 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13620}.**.** T
21190 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
211a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
211b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
211c0 20 6e 2d 74 68 0a 2a 2a 20 53 51 4c 20 70 61 72   n-th.** SQL par
211d0 61 6d 65 74 65 72 20 69 6e 20 61 20 5b 70 72 65  ameter in a [pre
211e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
211f0 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
21200 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
21210 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
21220 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
21230 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
21240 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
21250 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
21260 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
21270 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
21280 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
21290 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
212a0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
212b0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
212c0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
212d0 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
212e0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
212f0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
21300 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
21310 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
21320 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
21330 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
21340 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
21350 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
21360 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
21370 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20   If the value n 
21380 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
21390 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70  or if the n-th p
213a0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
213b0 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
213c0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
213d0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
213e0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
213f0 73 20 69 6e 20 74 68 65 20 55 54 46 2d 38 20 65  s in the UTF-8 e
21400 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
21410 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
21420 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
21430 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
21440 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
21450 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
21460 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
21470 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21480 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
21490 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
214a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
214b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
214c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
214d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
214e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
214f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21500 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
21510 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
21520 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3621} The [sqlit
21530 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21540 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  r_name(S,N)] int
21550 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
21560 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46  *          a UTF
21570 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
21580 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21590 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
215a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
215b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
215c0 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78  ] S having index
215d0 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20   N, or.**       
215e0 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65     NULL if there
215f0 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d   is no SQL param
21600 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20  eter with index 
21610 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20  N or if the.**  
21620 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
21630 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69  r with index N i
21640 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70  s an anonymous p
21650 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f  arameter "?"..*/
21660 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
21670 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21680 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
21690 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
216a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
216b0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
216c0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
216d0 20 4e 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a   Name {F13640}.*
216e0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
216f0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
21700 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
21710 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a  its name.  The.*
21720 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
21730 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
21740 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
21750 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
21760 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
21770 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
21780 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20  te3_bind()].  A 
21790 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
217a0 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
217b0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
217c0 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61  found.  The para
217d0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
217e0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
217f0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
21800 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
21810 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
21820 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
21830 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
21840 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
21850 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
21860 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
21870 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
21880 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
21890 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
218a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
218b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
218c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
218d0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
218e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
218f0 46 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c  F13641} The [sql
21900 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21910 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20  ter_index(S,N)] 
21920 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
21930 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
21940 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  e index of SQL p
21950 61 72 61 6d 65 74 65 72 20 69 6e 20 5b 70 72 65  arameter in [pre
21960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 77  .**          S w
21980 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65  hose name matche
21990 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69  s the UTF-8 stri
219a0 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68  ng N, or 0 if th
219b0 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ere is.**       
219c0 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a     no match..*/.
219d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
219e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
219f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21a00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
21a10 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
21a20 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
21a30 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
21a40 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
21a50 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43  {F13660}.**.** C
21a60 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
21a70 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
21a80 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
21a90 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ()] does not.** 
21aa0 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74  reset the [sqlit
21ab0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
21ac0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a  indings] on a .*
21ad0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
21ae0 65 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69  ement].  Use thi
21af0 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20  s routine to.** 
21b00 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
21b10 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
21b20 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
21b30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
21b40 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
21b50 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
21b60 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
21b70 73 65 74 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  sets all.**     
21b80 20 20 20 20 20 53 51 4c 20 70 61 72 61 6d 65 74       SQL paramet
21b90 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 5b  er bindings in [
21ba0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21bb0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
21bc0 20 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a    back to NULL..
21bd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
21be0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
21bf0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
21c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
21c10 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
21c20 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
21c30 20 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F13710}.**.** 
21c40 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
21c50 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
21c60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
21c70 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 0a  eturned by the .
21c80 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21c90 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
21ca0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 0a  utine returns 0.
21cb0 2a 2a 20 69 66 20 70 53 74 6d 74 20 69 73 20 61  ** if pStmt is a
21cc0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
21cd0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
21ce0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 0a  turn data (for .
21cf0 2a 2a 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50  ** example an UP
21d00 44 41 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  DATE)..**.** INV
21d10 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
21d20 46 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c  F13711} The [sql
21d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
21d40 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
21d50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
21d60 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
21d70 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65    columns in the
21d80 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65   result set gene
21d90 72 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  rated by the.** 
21da0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
21db0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
21dc0 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20   or 0 if S does 
21dd0 6e 6f 74 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20  not generate.** 
21de0 20 20 20 20 20 20 20 20 20 61 20 72 65 73 75 6c           a resul
21df0 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  t set..*/.int sq
21e00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
21e10 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
21e20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
21e30 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
21e40 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
21e50 6c 74 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a  lt Set {F13720}.
21e60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
21e70 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
21e80 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
21e90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
21ea0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
21eb0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
21ec0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
21ed0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f    The sqlite3_co
21ee0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
21ef0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
21f00 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
21f10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
21f20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  UTF8 string.** a
21f30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
21f40 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
21f50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
21f60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
21f70 64 0a 2a 2a 20 55 54 46 31 36 20 73 74 72 69 6e  d.** UTF16 strin
21f80 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
21f90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
21fa0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
21fb0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c  ement] that impl
21fc0 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43  ements the SELEC
21fd0 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  T statement..** 
21fe0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
21ff0 65 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75  eter is the colu
22000 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  mn number.  The 
22010 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
22020 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e   is.** number 0.
22030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  .**.** The retur
22040 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
22050 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
22060 6c 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a  l either the .**
22070 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22080 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
22090 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
220a0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72  inalize()].** or
220b0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
220c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
220d0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
220e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
220f0 65 31 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20  e16().** on the 
22100 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
22110 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
22120 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
22130 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
22140 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
22150 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
22160 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
22170 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
22180 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
22190 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
221a0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
221b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  d..**.** The nam
221c0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
221d0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
221e0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
221f0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
22200 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
22210 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
22220 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
22230 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
22240 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
22250 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
22260 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
22270 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
22280 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
22290 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
222a0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ext..**.** INVAR
222b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
222c0 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73 66  3721} A successf
222d0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
222e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
222f0 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a  lumn_name(S,N)].
22300 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
22310 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22320 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
22330 20 20 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f     of the Nth co
22340 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
22350 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63   the left-most c
22360 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 0a 2a  olumn) for the.*
22370 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
22380 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
22390 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
223a0 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  as a.**         
223b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
223c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
223d0 2a 0a 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41 20  *.** {F13723} A 
223e0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
223f0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
22400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22410 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
22420 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
22430 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
22440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
22450 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
22460 77 68 65 72 65 20 30 20 69 73 20 74 68 65 20 6c  where 0 is the l
22470 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  eft-most column)
22480 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
22490 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
224a0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
224b0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a  tement] S as a.*
224c0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
224d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
224e0 36 20 73 74 72 69 6e 67 20 69 6e 20 74 68 65 20  6 string in the 
224f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
22500 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34  r..**.** {F13724
22510 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
22520 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
22530 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
22540 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20  n_name16()].**  
22550 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
22560 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
22570 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79   pointer if they
22580 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a   are unable to.*
22590 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
225a0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
225b0 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20  ld their normal 
225c0 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a  return strings..
225d0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49  **.** {F13725} I
225e0 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
225f0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  r to [sqlite3_co
22600 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  lumn_name(S,N)] 
22610 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22630 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f  ame16(S,N)] is o
22640 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
22650 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
22660 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
22670 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
22680 65 72 2e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 33 37  er..** .** {F137
22690 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
226a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
226b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
226c0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
226d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
226e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
226f0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
22700 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
22710 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
22720 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
22730 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
22740 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
22750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
22760 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
22770 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
22780 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alled..**.** {F1
22790 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
227a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
227b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
227c0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
227d0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
227e0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
227f0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
22800 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
22810 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
22820 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
22830 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
22840 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22850 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
22860 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22870 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
22880 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22890 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
228a0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
228b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
228c0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
228d0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
228e0 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F13740}.**.** 
228f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
22900 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
22910 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
22920 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
22930 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
22940 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
22950 75 6c 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  ult of a SELECT 
22960 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
22970 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
22980 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
22990 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
229a0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
229b0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
229c0 72 20 61 20 55 54 46 38 20 6f 72 20 55 54 46 31  r a UTF8 or UTF1
229d0 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f  6 string.  The _
229e0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
229f0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
22a00 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
22a10 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
22a20 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
22a30 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
22a40 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
22a50 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22a60 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
22a70 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
22a80 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
22a90 75 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 70 72  until.** the [pr
22aa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22ab0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  ] is destroyed u
22ac0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
22ad0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22ae0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
22af0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
22b00 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
22b10 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
22b20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
22b30 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
22b40 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
22b50 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
22b60 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
22b70 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
22b80 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
22b90 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
22ba0 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
22bb0 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
22bc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22bd0 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20  ment]..** These 
22be0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
22bf0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
22c00 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
22c10 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  n returned by .*
22c20 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
22c30 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
22c40 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
22c50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
22c60 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
22c70 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
22c80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
22c90 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  n expression.** 
22ca0 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  or subquery and 
22cb0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
22cc0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
22cd0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
22ce0 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e 55 4c  ns.** return NUL
22cf0 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
22d00 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
22d10 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
22d20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
22d30 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  on error occurs.
22d40 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
22d50 79 20 72 65 74 75 72 6e 20 74 68 65 20 0a 2a 2a  y return the .**
22d60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
22d70 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
22d80 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
22d90 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
22da0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 77 61 73  lt.** column was
22db0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
22dc0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
22dd0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
22de0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
22df0 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
22e00 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
22e10 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
22e20 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
22e30 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
22e40 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
22e50 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
22e60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
22e70 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
22e80 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
22e90 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e  he .** SQLITE_EN
22ea0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
22eb0 44 41 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f  DATA preprocesso
22ec0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
22ed0 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d  ..**.** {U13751}
22ee0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
22ef0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
22f00 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
22f10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
22f20 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
22f30 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
22f40 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
22f50 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
22f60 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
22f70 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
22f80 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
22f90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
22fa0 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  741} The [sqlite
22fb0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
22fc0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
22fd0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
22fe0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
22ff0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
23000 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
23010 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23020 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
23030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
23040 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
23050 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
23060 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
23070 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
23080 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
23090 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
230a0 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
230b0 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
230c0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
230d0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
230e0 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
230f0 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
23100 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
23110 20 20 0a 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54    .** {F13742} T
23120 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23130 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
23140 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
23150 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
23160 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
23170 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
23180 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
23190 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
231a0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
231b0 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
231c0 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20   which the .**  
231d0 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
231e0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72  lt column of [pr
231f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23200 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S .**         
23210 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
23220 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
23230 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73  h column of S is
23240 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67   a.**          g
23250 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
23260 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
23270 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
23280 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
23290 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
232a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a  .**          .**
232b0 20 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {F13743} The [s
232c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
232d0 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
232e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
232f0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
23300 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
23310 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
23320 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
23330 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
23340 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
23350 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
23360 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23370 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
23380 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
23390 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
233a0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
233b0 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
233c0 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
233d0 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
233e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
233f0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
23400 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
23410 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
23420 20 0a 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54 68   .** {F13744} Th
23430 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23440 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
23450 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
23460 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
23470 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
23480 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
23490 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
234a0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
234b0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
234c0 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20  able from which 
234d0 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
234e0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
234f0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
23500 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
23510 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
23520 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
23530 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
23540 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
23550 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
23560 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
23570 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
23580 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
23590 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
235a0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
235b0 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
235c0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
235d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
235e0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
235f0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
23600 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
23610 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
23620 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
23630 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
23640 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
23650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
23660 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
23670 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
23680 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20  ement] S .**    
23690 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74        is extract
236a0 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
236b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
236c0 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20   S is a.**      
236d0 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72      general expr
236e0 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61  ession or if una
236f0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
23700 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20  memory.**       
23710 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20     to store the 
23720 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20  name..**        
23730 20 20 0a 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54    .** {F13746} T
23740 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23750 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
23760 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23770 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23780 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23790 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
237a0 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
237b0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
237c0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
237d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72   table column fr
237e0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
237f0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
23800 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
23810 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23820 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
23830 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
23840 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
23850 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
23860 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
23870 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
23880 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
23890 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
238a0 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
238b0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
238c0 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a  e..**          .
238d0 2a 2a 20 7b 46 31 33 37 34 38 7d 20 54 68 65 20  ** {F13748} The 
238e0 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72  return values fr
238f0 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  om.**          [
23900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23910 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c  atabase_name|col
23920 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
23930 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20  erfaces].**     
23940 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 0a 2a       are valid.*
23950 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74  *          for t
23960 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
23970 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23980 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
23990 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65      or until the
239a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61   encoding is cha
239b0 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20  nged by another 
239c0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
239d0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
239e0 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65  all for the same
239f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
23a00 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  ent and column..
23a10 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
23a20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37 35 31  S:.**.** {U13751
23a30 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  } If two or more
23a40 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
23a50 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
23a60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
23a70 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
23a80 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  ame|column metad
23a90 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
23aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23ab0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
23ac0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
23ad0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
23ae0 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
23af0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
23b00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
23b10 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
23b20 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23b30 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
23b40 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
23b50 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
23b60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23b70 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
23b80 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
23b90 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
23ba0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
23bb0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
23bc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23bd0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23be0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
23bf0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
23c00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
23c10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23c20 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
23c30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
23c40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
23c50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23c60 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
23c70 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23c80 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
23c90 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
23ca0 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
23cb0 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37  ery Result {F137
23cc0 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  60}.**.** The fi
23cd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
23ce0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
23cf0 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a 20 49 66 20  tement]. .** If 
23d00 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
23d10 73 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65  s a SELECT state
23d20 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
23d30 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 0a   column of the .
23d40 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
23d50 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 53  lt set of that S
23d60 45 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65  ELECT is a table
23d70 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
23d80 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
23d90 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
23da0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
23db0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
23dc0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
23dd0 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74  rned.  If the Nt
23de0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
23df0 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
23e00 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
23e10 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
23e20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23e30 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
23e40 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
23e50 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
23e60 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 20 7b 45  F-8 encoded.  {E
23e70 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ND} .** For exam
23e80 70 6c 65 2c 20 69 6e 20 74 68 65 20 64 61 74 61  ple, in the data
23e90 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
23ea0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
23eb0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
23ec0 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f  **.** And the fo
23ed0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
23ee0 74 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  t compiled:.**.*
23ef0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
23f00 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
23f10 2a 2a 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75  ** Then this rou
23f20 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
23f30 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
23f40 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
23f50 65 63 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20  econd.** result 
23f60 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
23f70 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
23f80 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
23f90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
23fa0 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53   (i==0)..**.** S
23fb0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
23fc0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
23fd0 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63  ng.  So just bec
23fe0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
23ff0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
24000 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
24010 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
24020 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
24030 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
24040 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
24050 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
24060 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
24070 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
24080 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
24090 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
240a0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70  not static.  Typ
240b0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
240c0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
240d0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
240e0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
240f0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
24100 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
24110 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
24120 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31  S:.**.** {F13761
24130 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  }  A successful 
24140 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
24150 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
24160 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
24170 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65      returns a ze
24180 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
24190 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
241a0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  ining the.**    
241b0 20 20 20 20 20 20 20 74 68 65 20 64 65 63 6c 61         the decla
241c0 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
241d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
241e0 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
241f0 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
24200 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
24210 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
24220 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
24230 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
24240 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24250 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
24260 2a 2a 20 7b 46 31 33 37 36 32 7d 20 20 41 20 73  ** {F13762}  A s
24270 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
24280 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
24290 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
242a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
242b0 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
242c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
242d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
242e0 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
242f0 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
24300 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
24310 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
24320 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
24330 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
24340 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
24350 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
24360 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
24370 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
24380 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
24390 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
243a0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
243b0 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
243c0 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
243d0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
243e0 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
243f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
24400 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
24410 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  in [prepared sta
24420 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
24430 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65         or if the
24440 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
24450 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
24460 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61  n or subquery ra
24470 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
24480 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63    than a table c
24490 6f 6c 75 6d 6e 20 6f 72 20 69 66 20 61 20 6d 65  olumn or if a me
244a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
244b0 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20  failure.**      
244c0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
244d0 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76  ng encoding conv
244e0 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a  ersions, then.**
244f0 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73             calls
24500 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
24510 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
24520 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
24530 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24540 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c  mn_decltype16(S,
24550 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  N)] return NULL.
24560 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
24570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24580 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
24590 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
245a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
245b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
245c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
245d0 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20 43 41  int);../* .** CA
245e0 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75 61 74  PI3REF:  Evaluat
245f0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
24600 6e 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a  nt {F13200}.**.*
24610 2a 20 41 66 74 65 72 20 61 6e 20 5b 70 72 65 70  * After an [prep
24620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24630 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
24640 64 20 77 69 74 68 20 61 20 63 61 6c 6c 0a 2a 2a  d with a call.**
24650 20 74 6f 20 65 69 74 68 65 72 20 5b 73 71 6c 69   to either [sqli
24660 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24670 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
24680 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
24690 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68   to one of.** th
246a0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
246b0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
246c0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
246d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
246e0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 66  ,.** then this f
246f0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
24700 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
24710 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
24720 75 61 74 65 20 74 68 65 20 0a 2a 2a 20 73 74 61  uate the .** sta
24730 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
24740 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
24750 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
24760 73 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  s sqlite3_step()
24770 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
24780 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
24790 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
247a0 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
247b0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
247c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
247d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
247e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
247f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
24800 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
24810 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
24820 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
24830 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
24840 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
24850 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
24860 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
24870 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
24880 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
24890 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
248a0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
248b0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
248c0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
248d0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
248e0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
248f0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
24900 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
24910 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
24920 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  Y], .** [SQLITE_
24930 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
24940 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
24950 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
24960 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
24970 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
24980 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
24990 6f 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  other [SQLITE_OK
249a0 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a   | result code].
249b0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
249c0 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
249d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
249e0 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
249f0 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c 2e 0a 2a  ed as.** well..*
24a00 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
24a10 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
24a20 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
24a30 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
24a40 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
24a50 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
24a60 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
24a70 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
24a80 61 74 65 6d 65 6e 74 20 69 73 20 61 20 43 4f 4d  atement is a COM
24a90 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  MIT.** or occurs
24aa0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
24ab0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
24ac0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
24ad0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
24ae0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
24af0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
24b00 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61 6e 64 20  ot a COMMIT and 
24b10 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
24b20 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
24b30 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
24b40 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
24b50 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
24b60 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
24b70 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  nuing..**.** [SQ
24b80 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
24b90 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
24ba0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
24bb0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
24bc0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
24bd0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
24be0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
24bf0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
24c00 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
24c10 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
24c20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
24c30 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
24c40 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
24c50 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
24c60 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
24c70 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ate..**.** If th
24c80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
24c90 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
24ca0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
24cb0 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54   then .** [SQLIT
24cc0 45 5f 52 4f 57 5d 20 69 73 20 72 65 74 75 72 6e  E_ROW] is return
24cd0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
24ce0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
24cf0 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f 72 20 70  s ready.** for p
24d00 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
24d10 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
24d20 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
24d30 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  sed using.** the
24d40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24d50 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e 20 61 63  _int | column ac
24d60 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
24d70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
24d80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
24d90 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
24da0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
24db0 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b 53 51 4c  ata..** .** [SQL
24dc0 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
24dd0 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
24de0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
24df0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
24e00 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
24e10 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
24e20 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
24e30 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
24e40 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
24e50 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
24e60 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
24e70 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
24e80 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
24e90 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63  * With the legac
24ea0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
24eb0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
24ec0 6f 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65  or code (example
24ed0 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  :.** [SQLITE_INT
24ee0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
24ef0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
24f00 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
24f10 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
24f20 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
24f30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
24f40 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
24f50 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
24f60 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
24f70 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24f80 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
24f90 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
24fa0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
24fb0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
24fc0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
24fd0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
24fe0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
24ff0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
25000 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
25010 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
25020 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
25030 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
25040 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
25050 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
25060 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
25070 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
25080 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
25090 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69 6f  t had .** previo
250a0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
250b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
250c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
250d0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
250e0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
250f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
25100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
25110 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
25120 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
25130 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
25140 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
25150 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
25160 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
25170 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20 6c  </b>.** In the l
25180 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
25190 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33   .** the sqlite3
251a0 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77 61  _step() API alwa
251b0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
251c0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
251d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
251e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
251f0 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  y error other th
25200 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
25210 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  .** and [SQLITE_
25220 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
25230 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  st call [sqlite3
25240 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
25250 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
25260 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
25270 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
25280 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 65 72   specific.** [er
25290 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
252a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
252b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
252c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
252d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
252e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
252f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
25300 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
25310 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
25320 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
25330 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
25340 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
25350 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
25360 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
25370 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25380 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
25390 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
253a0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
253b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
253c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
253d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a 20  ], then the .** 
253e0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
253f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
25400 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
25410 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
25420 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
25430 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
25440 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
25450 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
25460 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
25470 46 31 33 32 30 32 7d 20 20 49 66 20 5b 70 72 65  F13202}  If [pre
25480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25490 20 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62   S is ready to b
254a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  e.**           r
254b0 75 6e 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  un, then [sqlite
254c0 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e  3_step(S)] advan
254d0 63 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65  ces that prepare
254e0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20  d statement.**  
254f0 20 20 20 20 20 20 20 20 20 75 6e 74 69 6c 20 74           until t
25500 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20  o completion or 
25510 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
25520 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
25530 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25540 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
25550 6c 74 20 73 65 74 20 6f 72 20 61 6e 20 69 6e 74  lt set or an int
25560 65 72 72 75 70 74 20 6f 72 20 72 75 6e 2d 74 69  errupt or run-ti
25570 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  me error occurs.
25580 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34 7d 20  .**.** {F15304} 
25590 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
255a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
255b0 5d 20 63 61 75 73 65 73 20 74 68 65 20 0a 2a 2a  ] causes the .**
255c0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
255d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
255e0 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
255f0 6c 65 74 69 6f 6e 2c 0a 2a 2a 20 20 20 20 20 20  letion,.**      
25600 20 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f       the functio
25610 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
25620 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
25630 46 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20  F15306}  When a 
25640 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25650 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20  _step(S)] stops 
25660 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65  because it is re
25670 61 64 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ady.**          
25680 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
25690 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  er row of the re
256a0 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74  sult set, it ret
256b0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
256c0 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a    [SQLITE_ROW]..
256d0 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20 20  **.** {F15308}  
256e0 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
256f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65  lite3_step(S)] e
25700 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20  ncounters an.** 
25710 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
25720 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e 74  e3_interrupt|int
25730 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
25740 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20  -time error,.** 
25750 20 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74            it ret
25760 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
25770 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  ate error code t
25780 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  hat is not one o
25790 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  f.**           [
257a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c  SQLITE_OK], [SQL
257b0 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51  ITE_ROW], or [SQ
257c0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
257d0 2a 20 7b 46 31 35 33 31 30 7d 20 20 49 66 20 61  * {F15310}  If a
257e0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
257f0 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d 20  rupt|interrupt] 
25800 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f  or run-time erro
25810 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  r.**           o
25820 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63  ccurs during a c
25830 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25840 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20  step(S)].**     
25850 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65        for a [pre
25860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25870 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67   S created using
25880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65  .**           le
25890 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20  gacy interfaces 
258a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
258b0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
258c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
258d0 70 61 72 65 31 36 28 29 5d 20 74 68 65 6e 20 74  pare16()] then t
258e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
258f0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
25900 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
25910 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERROR], [SQLITE_
25920 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BUSY], or [SQLIT
25930 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e  E_MISUSE]..*/.in
25940 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
25950 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
25960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25970 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
25980 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
25990 74 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a  t {F13770}.**.**
259a0 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
259b0 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20  er of values in 
259c0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
259d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
259e0 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
259f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
25a00 37 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c  71}  After a cal
25a10 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
25a20 65 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75  ep(S)] that retu
25a30 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
25a40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
25a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  he [sqlite3_data
25a60 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69  _count(S)] routi
25a70 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ne.**           
25a80 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
25a90 73 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68  same value as th
25aa0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
25ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
25ac0 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f  ount(S)] functio
25ad0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 32  n..**.** {F13772
25ae0 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65  }  After [sqlite
25af0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72  3_step(S)] has r
25b00 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75  eturned any valu
25b10 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
25b20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
25b30 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65  E_ROW] or before
25b40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25b50 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a 20  )] has been .** 
25b60 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65 64            called
25b70 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
25b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72  d statement] for
25b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
25ba0 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e  e first time sin
25bb0 63 65 20 69 74 20 77 61 73 20 5b 73 71 6c 69 74  ce it was [sqlit
25bc0 65 33 5f 70 72 65 70 61 72 65 7c 70 72 65 70 61  e3_prepare|prepa
25bd0 72 65 64 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  red].**         
25be0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65    or [sqlite3_re
25bf0 73 65 74 7c 72 65 73 65 74 5d 2c 20 74 68 65 20  set|reset], the 
25c00 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
25c10 75 6e 74 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  unt(S)].**      
25c20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 72 65 74       routine ret
25c30 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
25c40 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
25c50 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
25c60 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25c70 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
25c80 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
25c90 73 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20 4b 45  s {F10265}.** KE
25ca0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
25cb0 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 36  EXT.**.** {F1026
25cc0 36 7d 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  6}Every value in
25cd0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
25ce0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
25cf0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
25d00 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
25d10 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
25d20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
25d30 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
25d40 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
25d50 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
25d60 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
25d70 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
25d80 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
25d90 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
25da0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
25db0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
25dc0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
25dd0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
25de0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
25df0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
25e00 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
25e10 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
25e20 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
25e30 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
25e40 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
25e50 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
25e60 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
25e70 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
25e80 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
25e90 45 33 5f 54 45 58 54 20 6e 6f 74 0a 2a 2a 20 53  E3_TEXT not.** S
25ea0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
25eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
25ec0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
25ed0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
25ee0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
25ef0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
25f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
25f10 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
25f20 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
25f30 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
25f40 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
25f50 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
25f60 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
25f70 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
25f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25f90 3a 20 52 65 73 75 6c 74 73 20 56 61 6c 75 65 73  : Results Values
25fa0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 46   From A Query {F
25fb0 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13800}.**.** The
25fc0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
25fd0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
25fe0 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
25ff0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
26000 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
26010 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
26020 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  .** a single col
26030 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
26040 6e 74 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  nt result row of
26050 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
26060 65 72 79 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  ery.** case the 
26070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
26080 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
26090 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
260a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
260b0 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61   is being.** eva
260c0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
260d0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74  ite3_stmt*] that
260e0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
260f0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
26100 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
26110 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
26120 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65  ants) and.** the
26130 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
26140 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
26150 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
26160 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
26170 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  n .** should be 
26180 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
26190 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
261a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
261b0 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65  t.** has an inde
261c0 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66  x of 0..**.** If
261d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
261e0 6e 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  nt is not curren
261f0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
26200 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
26210 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d  the.** the colum
26220 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
26230 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
26240 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
26250 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  . .** These rout
26260 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
26270 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
26280 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
26290 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
262a0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
262b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
262c0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
262d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
262e0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
262f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73  _finalize()] has
26300 20 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65   been call subse
26310 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
26320 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
26330 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
26340 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
26350 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
26360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26370 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
26380 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
26390 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
263a0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
263b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
263c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
263d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
263e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
263f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
26400 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
26410 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
26420 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
26430 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
26440 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
26450 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
26460 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
26470 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
26480 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
26490 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c    .**.** The sql
264a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
264b0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
264c0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  ns .** [SQLITE_I
264d0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
264e0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
264f0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
26500 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
26510 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
26520 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
26530 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
26540 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
26550 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
26560 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
26570 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
26580 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
26590 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
265a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
265b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
265c0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
265d0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
265e0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
265f0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
26600 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
26610 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
26620 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
26630 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
26640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26650 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
26660 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
26670 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26680 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
26690 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
266a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
266b0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
266c0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
266d0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
266e0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
266f0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
26700 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
26710 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
26720 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74   .** routine ret
26730 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
26740 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
26750 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
26760 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
26770 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
26780 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
26790 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
267a0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
267b0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
267c0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
267d0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
267e0 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68   bytes..** If th
267f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
26800 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
26810 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26820 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
26830 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
26840 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
26850 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
26860 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
26870 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
26880 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
26890 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
268a0 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
268b0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
268c0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
268d0 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
268e0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
268f0 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61  string.  For cla
26900 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
26910 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
26920 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
26930 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
26940 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
26950 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
26960 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65  **.** Strings re
26970 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
26980 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
26990 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
269a0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
269b0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
269c0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
269d0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
269e0 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
269f0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
26a00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
26a10 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
26a20 68 20 62 6c 6f 62 20 69 73 20 61 6e 20 61 72 62  h blob is an arb
26a30 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
26a40 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
26a50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
26a60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26a70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26a80 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
26a90 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
26aa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
26ab0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
26ac0 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
26ad0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
26ae0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
26af0 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20   of UTF-8.  .** 
26b00 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
26b10 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
26b20 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
26b30 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
26b40 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
26b50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26b60 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
26b70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
26b80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26b90 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
26ba0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26bb0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
26bc0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
26bd0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
26be0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
26bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26c00 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
26c10 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
26c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26c30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
26c40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
26c50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
26c60 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
26c70 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
26c80 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
26c90 75 74 69 6e 65 73 20 6c 69 6b 65 20 0a 2a 2a 20  utines like .** 
26ca0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
26cb0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
26cc0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
26cd0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
26ce0 5f 62 79 74 65 73 28 29 5d 2c 0a 2a 2a 20 74 68  _bytes()],.** th
26cf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
26d00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
26d10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
26d20 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
26d30 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
26d40 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
26d50 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
26d60 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
26d70 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
26d80 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
26d90 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
26da0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
26db0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
26dc0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
26dd0 72 6e 61 6c 6c 79 20 74 6f 20 64 6f 20 74 68 65  rnally to do the
26de0 20 63 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 20 61   conversion.** a
26df0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
26e00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
26e10 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
26e20 6f 6e 76 65 72 73 69 6f 6e 73 20 74 68 61 74 0a  onversions that.
26e30 2a 2a 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  ** are applied:.
26e40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
26e50 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
26e60 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
26e70 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
26e80 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
26e90 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
26ea0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
26eb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26ec0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
26ed0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
26ee0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
26ef0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
26f00 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
26f10 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
26f20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
26f30 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
26f40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
26f50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
26f60 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
26f70 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
26f80 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
26f90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
26fa0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
26fb0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26fc0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
26fd0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
26fe0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
26ff0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
27000 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
27010 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
27020 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
27030 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
27040 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
27050 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 66 6f 72  <td> Same as for
27060 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
27070 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
27080 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
27090 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
270a0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
270b0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
270c0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
270d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
270e0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
270f0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
27100 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
27110 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
27120 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
27130 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
27140 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
27150 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
27160 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
27170 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
27180 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
27190 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
271a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
271b0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
271c0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
271d0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
271e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
271f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
27200 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
27210 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
27220 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
27230 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
27240 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
27250 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
27260 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
27270 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
27280 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
27290 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
272a0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
272b0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
272c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
272d0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
272e0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
272f0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
27300 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
27310 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
27320 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
27330 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
27340 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
27350 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
27360 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
27370 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
27380 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
27390 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
273a0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
273b0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
273c0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
273d0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
273e0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
273f0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
27400 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
27410 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
27420 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
27430 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
27440 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
27450 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27460 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
27470 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
27480 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
27490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
274a0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
274b0 69 64 61 74 65 64 2e 20 0a 2a 2a 20 54 79 70 65  idated. .** Type
274c0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
274d0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
274e0 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
274f0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
27500 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
27510 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
27520 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
27530 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
27540 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
27550 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 0a 2a 2a  olumn_text() .**
27560 20 20 20 20 20 20 20 20 20 20 6f 72 20 73 71 6c            or sql
27570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27580 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
27590 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
275a0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
275b0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
275c0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
275d0 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a  ing.</p></li>.**
275e0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
275f0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
27600 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
27610 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
27620 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
27630 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74  *          sqlit
27640 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
27650 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
27660 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
27670 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
27680 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
27690 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 0a  16.</p></li>.**.
276a0 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20  ** <li><p>  The 
276b0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
276c0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
276d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
276e0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
276f0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
27700 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
27710 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
27720 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
27730 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
27740 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
27750 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  p></li>.** </ul>
27760 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
27770 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
27780 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
27790 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
277a0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
277b0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
277c0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
277d0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
277e0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
277f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
27800 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
27810 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
27820 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
27830 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
27840 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
27850 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
27860 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
27870 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
27880 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 20 69 74   but sometime it
27890 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69   is.** not possi
278a0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
278b0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
278c0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
278d0 64 61 74 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  dated.  .**.** T
278e0 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
278f0 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
27900 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
27910 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
27920 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
27930 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
27940 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 20 3c 75 6c  ways:.**.**  <ul
27950 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
27960 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
27970 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
27980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27990 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
279a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
279b0 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
279c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
279d0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
279e0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
279f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
27a00 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
27a10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
27a20 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 2f 75 6c  ()</li>.**  </ul
27a30 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
27a40 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
27a50 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
27a60 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 73  column_text(), s
27a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
27a80 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20 73 71 6c 69  ob(),.** or sqli
27a90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
27aa0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
27ab0 63 65 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  ce the result in
27ac0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 0a 2a  to the desired.*
27ad0 2a 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  * format, then i
27ae0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
27af0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 20  lumn_bytes() or 
27b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27b10 79 74 65 73 31 36 28 29 20 74 6f 0a 2a 2a 20 66  ytes16() to.** f
27b20 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
27b30 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
27b40 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 20 74 6f 20  not mix call to 
27b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27b60 65 78 74 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ext() or.** sqli
27b70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27b80 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
27b90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27ba0 79 74 65 73 31 36 28 29 2e 20 20 41 6e 64 20 64  ytes16().  And d
27bb0 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78 20 63 61 6c  o not.** mix cal
27bc0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
27bd0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 77 69  lumn_text16() wi
27be0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
27bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27c00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
27c10 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
27c20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
27c30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
27c40 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
27c50 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
27c60 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
27c70 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
27c80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
27c90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
27ca0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
27cb0 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
27cc0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
27cd0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
27ce0 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65 65  nd blobs is free
27cf0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
27d00 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
27d10 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
27d20 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
27d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
27d40 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
27d50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
27d60 65 74 63 2e 20 69 6e 74 6f 20 0a 2a 2a 20 5b 73  etc. into .** [s
27d70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
27d80 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
27d90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
27da0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
27db0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
27dc0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
27dd0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
27de0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
27df0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
27e00 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
27e10 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
27e20 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
27e30 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
27e40 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
27e50 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
27e60 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
27e70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
27e80 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
27e90 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
27ea0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
27eb0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
27ec0 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  13803} The [sqli
27ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27ee0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
27ef0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
27f00 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
27f10 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
27f20 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
27f30 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
27f40 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
27f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27f60 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64 20  into a blob and 
27f70 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a  then returns a.*
27f80 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
27f90 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
27fa0 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
27fb0 20 7b 46 31 33 38 30 36 7d 20 54 68 65 20 5b 73   {F13806} The [s
27fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27fd0 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  tes(S,N)] interf
27fe0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
27ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
28000 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
28010 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e  he blob or strin
28020 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
28030 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28040 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
28050 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
28060 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
28070 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
28080 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
28090 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
280a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e  _column_blob(S,N
280b0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
280c0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
280d0 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a  n_text(S,N)]..**
280e0 0a 2a 2a 20 7b 46 31 33 38 30 39 7d 20 54 68 65  .** {F13809} The
280f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28100 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69  _bytes16(S,N)] i
28110 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28120 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28130 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28140 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28   in the string (
28150 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
28160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
28170 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
28180 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
28190 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
281a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
281b0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
281c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
281d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29  lumn_text16(S,N)
281e0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32  ]..**.** {F13812
281f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
28200 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e  olumn_double(S,N
28210 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28220 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28230 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
28240 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
28250 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
28260 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
28270 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
28280 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
28290 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
282a0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
282b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
282c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
282d0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  value..**.** {F1
282e0 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3815} The [sqlit
282f0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c  e3_column_int(S,
28300 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
28310 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
28320 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
28330 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
28340 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
28350 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
28360 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
28370 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
28380 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
28390 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
283a0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
283b0 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
283c0 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
283d0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eger..**.** {F13
283e0 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  818} The [sqlite
283f0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53  3_column_int64(S
28400 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
28410 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28420 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
28430 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
28440 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
28450 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
28460 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
28470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
28480 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
28490 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
284a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
284b0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
284c0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
284d0 2a 20 7b 46 31 33 38 32 31 7d 20 54 68 65 20 5b  * {F13821} The [
284e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
284f0 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ext(S,N)] interf
28500 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
28510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
28520 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
28530 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
28540 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
28550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
28560 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28570 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  ] S into a zero-
28580 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
28590 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74   .**          st
285a0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
285b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
285c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
285d0 20 7b 46 31 33 38 32 34 7d 20 54 68 65 20 5b 73   {F13824} The [s
285e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
285f0 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  xt16(S,N)] inter
28600 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
28610 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
28620 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
28630 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
28640 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
28650 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  r.**          [p
28660 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28670 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
28680 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
28690 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
286a0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
286b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
286c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
286d0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
286e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
286f0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
28700 46 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c  F13827} The [sql
28710 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28720 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28730 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
28740 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
28750 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
28760 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
28770 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
28780 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
28790 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
287a0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
287b0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
287c0 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20          the Nth 
287d0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
287e0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
287f0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
28800 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
28810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28820 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 33   S..**.** {F1383
28830 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
28840 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e  column_value(S,N
28850 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28860 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
28870 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e     pointer to an
28880 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
28890 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
288a0 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ect for the.**  
288b0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
288c0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
288d0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
288e0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
288f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
28900 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
28910 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
28920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
28930 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
28940 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
28950 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28960 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
28970 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
28980 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
28990 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
289a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
289b0 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
289c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
289d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
289e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
289f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
28a00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
28a10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
28a20 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
28a30 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
28a40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28a50 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
28a60 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
28a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28a80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
28a90 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
28aa0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
28ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28ad0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
28ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28af0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28b00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
28b10 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
28b20 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
28b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28b40 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
28b50 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
28b60 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
28b70 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
28b80 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13300}.**.** The
28b90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
28ba0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
28bb0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
28bc0 20 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64   a .** [prepared
28bd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66 20   statement]. If 
28be0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
28bf0 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73 75  s.** executed su
28c00 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20 6e  ccessfully, or n
28c10 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
28c20 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ll, then SQLITE_
28c30 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  OK is returned..
28c40 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  ** If execution 
28c50 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
28c60 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 20   failed then an 
28c70 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
28c80 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
28c90 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
28ca0 72 65 74 75 72 6e 65 64 2e 20 0a 2a 2a 0a 2a 2a  returned. .**.**
28cb0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
28cc0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
28cd0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
28ce0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
28cf0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
28d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
28d10 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
28d20 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a  chine has not .*
28d30 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
28d40 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
28d50 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
28d60 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
28d70 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
28d80 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69  an error or an i
28d90 6e 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20  nterrupt.  (See 
28da0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
28db0 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f  pt()].) .** Inco
28dc0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
28dd0 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
28de0 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
28df0 6e 73 20 63 61 6e 63 65 6c 65 64 2c 20 20 0a 2a  ns canceled,  .*
28e00 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
28e10 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
28e20 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b 65  , and the .** [e
28e30 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72  rror code] retur
28e40 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
28e50 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
28e60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
28e70 0a 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65  .** {F11302} The
28e80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28e90 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  ze(S)] interface
28ea0 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a   destroys the.**
28eb0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
28ec0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
28ed0 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c   and releases al
28ee0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  l.**          me
28ef0 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65  mory and file re
28f00 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20  sources held by 
28f10 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  that object..**.
28f20 2a 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74  ** {F11304} If t
28f30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
28f40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28f50 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
28f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
28f70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28f80 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20  ] S returned an 
28f90 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20  error,.**       
28fa0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
28fb0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65  _finalize(S)] re
28fc0 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20  turns that same 
28fd0 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  error..*/.int sq
28fe0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
28ff0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
29000 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
29010 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
29020 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29030 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d   Object {F13330}
29040 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
29050 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
29060 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
29070 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 70 72   reset a .** [pr
29080 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29090 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 62 61 63  ] object..** bac
290a0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
290b0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
290c0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
290d0 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
290e0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
290f0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
29100 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
29110 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
29120 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
29130 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29140 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
29150 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
29160 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
29170 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
29180 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
29190 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  gs..**.** {F1133
291a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
291b0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
291c0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
291d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
291e0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
291f0 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
29200 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
29210 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rogram..**.** {F
29220 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
29230 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
29240 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
29250 53 29 5d 20 66 6f 72 20 0a 2a 2a 20 20 20 20 20  S)] for .**     
29260 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
29270 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
29280 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
29290 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
292a0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
292b0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
292c0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
292d0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
292e0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20  lled on S,.**   
292f0 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
29300 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
29310 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
29320 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  K]..**.** {F1133
29330 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  6} If the most r
29340 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
29350 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29360 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
29370 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29380 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
29390 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
293a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
293b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
293c0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
293d0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
293e0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  e]..**.** {F1133
293f0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
29400 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
29410 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
29420 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
29430 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e  *          of an
29440 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
29450 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
29460 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
29470 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
29480 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
29490 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
294a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
294b0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
294c0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
294d0 63 74 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a  ctions {F16100}.
294e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
294f0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
29500 72 6f 75 74 69 6e 65 73 7d 20 0a 2a 2a 0a 2a 2a  routines} .**.**
29510 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
29520 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
29530 6c 79 20 6b 6e 6f 77 6e 20 61 73 0a 2a 2a 20 22  ly known as.** "
29540 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
29550 6e 20 72 6f 75 74 69 6e 65 73 22 29 20 61 72 65  n routines") are
29560 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
29570 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
29580 67 72 65 67 61 74 65 73 0a 2a 2a 20 6f 72 20 74  gregates.** or t
29590 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
295a0 65 68 61 76 69 6f 72 20 6f 66 20 65 78 69 73 74  ehavior of exist
295b0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
295c0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
295d0 20 20 54 68 65 0a 2a 2a 20 64 69 66 66 65 72 65    The.** differe
295e0 6e 63 65 20 6f 6e 6c 79 20 62 65 74 77 65 65 6e  nce only between
295f0 20 74 68 65 20 74 77 6f 20 69 73 20 74 68 61 74   the two is that
29600 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
29610 6d 65 74 65 72 2c 20 74 68 65 0a 2a 2a 20 6e 61  meter, the.** na
29620 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
29630 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  r) function or a
29640 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
29650 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
29660 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  r.** sqlite3_cre
29670 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
29680 6e 64 20 55 54 46 2d 31 36 20 66 6f 72 20 73 71  nd UTF-16 for sq
29690 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
296a0 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
296b0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
296c0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
296d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
296e0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
296f0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
29700 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
29710 49 66 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 70  If a single.** p
29720 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65  rogram uses more
29730 20 74 68 61 6e 20 6f 6e 65 20 5b 64 61 74 61 62   than one [datab
29740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29750 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e  internally, then
29760 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
29770 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
29780 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20  individually to 
29790 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
297a0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
297b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
297c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
297d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
297e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
297f0 61 74 65 64 0a 2a 2a 20 6f 72 20 72 65 64 65 66  ated.** or redef
29800 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e  ined..** The len
29810 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
29820 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
29830 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
29840 76 65 20 6f 66 20 74 68 65 20 0a 2a 2a 20 7a 65  ve of the .** ze
29850 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
29860 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
29870 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
29880 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
29890 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
298a0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
298b0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
298c0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
298d0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
298e0 75 6c 74 20 69 6e 20 61 6e 20 53 51 4c 49 54 45  ult in an SQLITE
298f0 5f 45 52 52 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a  _ERROR error..**
29900 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61  .** The third pa
29910 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
29920 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
29930 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
29940 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
29950 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
29960 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
29970 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
29980 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
29990 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
299a0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
299b0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
299c0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
299d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
299e0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
299f0 63 69 66 69 65 73 20 77 68 61 74 20 0a 2a 2a 20  cifies what .** 
29a00 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
29a10 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
29a20 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
29a30 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
29a40 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
29a50 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
29a60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29a70 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
29a80 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
29a90 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
29aa0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
29ab0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
29ac0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
29ad0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
29ae0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
29af0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
29b00 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
29b10 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
29b20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29b30 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
29b40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29b50 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
29b60 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
29b70 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
29b80 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
29b90 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
29ba0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
29bb0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
29bc0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
29bd0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
29be0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
29bf0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
29c00 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
29c10 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
29c20 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
29c30 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
29c40 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
29c50 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
29c60 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
29c70 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
29c80 61 74 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  at.** text encod
29c90 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
29ca0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
29cb0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 0a  ument should be.
29cc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  ** [SQLITE_ANY].
29cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
29ce0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
29cf0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
29d00 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
29d10 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
29d20 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  e function can g
29d30 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
29d40 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
29d50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  .** [sqlite3_use
29d60 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
29d70 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
29d80 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
29d90 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
29da0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
29db0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
29dc0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
29dd0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
29de0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
29df0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6f  QL.** function o
29e00 72 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  r aggregate. A s
29e10 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
29e20 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
29e30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
29e40 0a 2a 2a 20 74 68 65 20 78 46 75 6e 63 20 63 61  .** the xFunc ca
29e50 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
29e60 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
29e70 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
29e80 68 65 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  he xStep.** and 
29e90 78 46 69 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  xFinal parameter
29ea0 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
29eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
29ec0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
29ed0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53  ntation.** of xS
29ee0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  tep and xFinal a
29ef0 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
29f00 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
29f10 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
29f20 0a 2a 2a 20 65 78 69 73 74 69 6e 67 20 53 51 4c  .** existing SQL
29f30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
29f40 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
29f50 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
29f60 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
29f70 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  backs..**.** It 
29f80 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
29f90 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
29fa0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29fb0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
29fc0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
29fd0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
29fe0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
29ff0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2a000 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2a010 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2a020 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2a030 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
2a040 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
2a050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
2a060 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
2a070 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
2a080 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
2a090 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
2a0a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2a0b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33  S:.**.** {F16103
2a0c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a0d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2a0e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
2a0f0 68 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a  haves exactly.**
2a100 20 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b            like [
2a110 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a120 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76  unction()] in ev
2a130 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74  ery way except t
2a140 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20  hat it.**       
2a150 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68     interprets th
2a160 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20  e zFunctionName 
2a170 61 72 67 75 6d 65 6e 74 20 61 73 0a 2a 2a 20 20  argument as.**  
2a180 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
2a190 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
2a1a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2a1b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 61   instead of as a
2a1c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2a1d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2a1e0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30  -8..**.** {F1610
2a1f0 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
2a200 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2a210 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2a220 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a230 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2a240 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
2a250 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
2a260 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2a270 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2a280 6f 6e 73 20 69 6e 20 5b 64 61 74 61 62 61 73 65  ons in [database
2a290 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
2a2a0 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20  *          used 
2a2b0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
2a2c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2a2d0 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
2a2e0 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
2a2f0 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61      and having a
2a300 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2a310 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a  encoding of E..*
2a320 2a 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41 20  *.** {F16109} A 
2a330 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2a340 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2a350 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2a360 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2a370 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63            replac
2a380 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20  es the P, F, S, 
2a390 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f  and L values fro
2a3a0 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  m any prior call
2a3b0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
2a3c0 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58     the same D, X
2a3d0 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65  , N, and E value
2a3e0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 32  s..**.** {F16112
2a3f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a400 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2a410 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,X,...)] interfa
2a420 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a  ce fails with.**
2a430 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
2a440 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
2a450 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65  TE_ERROR] if the
2a460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2a470 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20  me X is.**      
2a480 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20      longer than 
2a490 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73  255 bytes exclus
2a4a0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20  ive of the zero 
2a4b0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2a4c0 2a 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68 65  * {F16118} Eithe
2a4d0 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c  r F must be NULL
2a4e0 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
2a4f0 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73   non-NULL or els
2a500 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e F.**          
2a510 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20  is non-NULL and 
2a520 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c  S and L are NULL
2a530 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20  , otherwise.**  
2a540 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2a550 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a560 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2a570 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2a580 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a  TE_ERROR]..**.**
2a590 20 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {F16121} The [s
2a5a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a5b0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
2a5c0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
2a5d0 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
2a5e0 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
2a5f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
2a600 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70  f there exist [p
2a610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a620 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts].**          
2a630 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2a640 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2a650 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
2a660 2a 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65 20  ** {F16124} The 
2a670 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a680 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2a690 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
2a6a0 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2a6b0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2a6c0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
2a6d0 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74  RROR] if paramet
2a6e0 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67  er N (specifying
2a6f0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
2a700 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d          of argum
2a710 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
2a720 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72  function being r
2a730 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65  egistered) is le
2a740 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
2a750 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2a760 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
2a770 2a 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e 20  * {F16127} When 
2a780 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2a790 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
2a7a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a7b0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2a7c0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2a7d0 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
2a7e0 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2a7f0 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
2a800 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2a810 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74    named X when t
2a820 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2a830 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2a840 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  L function is.**
2a850 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c            exactl
2a860 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  y N..**.** {F161
2a870 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31  30} When N is -1
2a880 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
2a890 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2a8a0 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2a8b0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2a8c0 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
2a8d0 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
2a8e0 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63  for the SQL func
2a8f0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2a900 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e   named X with an
2a910 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2a920 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ments..**.** {F1
2a930 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6133} When calls
2a940 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2a950 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2a960 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2a970 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c       specify mul
2a980 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2a990 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2a9a0 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  e function X.** 
2a9b0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
2a9c0 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n one implementa
2a9d0 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e  tion has N>=0 an
2a9e0 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20  d the other has 
2a9f0 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20  N=(-1).**       
2aa00 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74     the implement
2aa10 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2aa20 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65  -zero N is prefe
2aa30 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
2aa40 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  136} When calls 
2aa50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2aa60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2aa70 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,E,...)].**    
2aa80 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2aa90 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2aaa0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2aab0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  me function X wi
2aac0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2aad0 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
2aae0 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75  f arguments N bu
2aaf0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
2ab00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
2ab10 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74  odings E, then t
2ab20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2ab30 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65  n where E matche
2ab40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2ab50 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64    database encod
2ab60 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64  ing is preferred
2ab70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39 7d  ..**.** {F16139}
2ab80 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
2ab90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
2aba0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
2abb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2abc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2abd0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
2abe0 4c 29 5d 20 74 68 65 20 66 69 6e 69 61 6c 69 7a  L)] the finializ
2abf0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  er.**          f
2ac00 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61  unction L will a
2ac10 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
2ac20 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
2ac30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ac40 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
2ac50 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
2ac60 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2ac70 0a 2a 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65  .** {F16142} Whe
2ac80 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
2ac90 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
2aca0 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
2acb0 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2acc0 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
2acd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2ace0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2acf0 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
2ad00 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
2ad10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ad20 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
2ad30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ad40 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
2ad50 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
2ad60 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
2ad70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
2ad80 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
2ad90 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
2ada0 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77  arameter are alw
2adb0 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ays [protected s
2adc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2add0 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  jects..*/.int sq
2ade0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2adf0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2ae00 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2ae10 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2ae20 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2ae30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2ae40 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2ae50 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2ae60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2ae70 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2ae80 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2ae90 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2aea0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2aeb0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2aec0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2aed0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2aee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2aef0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2af00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2af10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2af20 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2af30 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2af40 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2af50 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2af60 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2af70 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2af80 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2af90 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2afa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2afb0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2afc0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2afd0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2afe0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
2aff0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
2b000 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36  Encodings {F1026
2b010 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  7}.**.** These c
2b020 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
2b030 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
2b040 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
2b050 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
2b060 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
2b070 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2b080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b090 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
2b0a0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b0b0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
2b0c0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2b0d0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
2b0e0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2b0f0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2b100 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2b110 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2b120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b130 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2b140 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2b150 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2b160 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2b170 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2b180 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2b190 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b1a0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2b1b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2b1c0 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e  bsolete Function
2b1d0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
2b1e0 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20  nctions are all 
2b1f0 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49  now obsolete.  I
2b200 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2b210 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2b220 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2b230 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2b240 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73  we continue to s
2b250 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20  upport.** these 
2b260 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65  functions.  Howe
2b270 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70  ver, new develop
2b280 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68  ment projects sh
2b290 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2b2a0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2b2b0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2b2c0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2b2d0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2b2e0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2b2f0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2b300 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2b310 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f  you want they do
2b320 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b330 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2b340 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b350 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2b360 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2b370 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
2b380 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2b390 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2b3a0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2b3b0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2b3c0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
2b3d0 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69  void);.void sqli
2b3e0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
2b3f0 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  up(void);.int sq
2b400 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2b410 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2b420 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2b430 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2b440 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
2b450 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2b460 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2b470 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2b480 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a  es {F15100}.**.*
2b490 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
2b4a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b4b0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
2b4c0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
2b4d0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
2b4e0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
2b4f0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
2b500 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
2b510 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
2b520 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2b530 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
2b540 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
2b550 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
2b560 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
2b570 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
2b580 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
2b590 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b5a0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2b5b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b5c0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
2b5d0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
2b5e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2b5f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2b600 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
2b610 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2b620 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
2b630 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
2b640 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
2b650 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
2b660 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b670 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
2b680 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
2b690 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
2b6a0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
2b6b0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2b6c0 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
2b6d0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
2b6e0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
2b6f0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
2b700 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b710 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
2b720 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
2b730 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
2b740 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b750 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
2b760 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
2b770 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2b780 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
2b790 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b7a0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
2b7b0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
2b7c0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
2b7d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2b7e0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
2b7f0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2b800 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  g .** [sqlite3_c
2b810 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20 73 71 6c  olumn_blob | sql
2b820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 20 72 6f  ite3_column_* ro
2b830 75 74 69 6e 65 73 5d 20 65 78 63 65 70 74 20 74  utines] except t
2b840 68 61 74 20 0a 2a 2a 20 74 68 65 73 65 20 72 6f  hat .** these ro
2b850 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2b860 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2b870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b880 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 0a 2a 2a  bject pointer.**
2b890 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2b8a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2b8b0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2b8c0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2b8d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2b8e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2b8f0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2b900 78 74 72 61 63 74 73 20 61 20 55 54 46 31 36 20  xtracts a UTF16 
2b910 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
2b920 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
2b930 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
2b940 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20  achine.  The.** 
2b950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2b960 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2b970 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2b980 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2b990 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 31  .** extract UTF1
2b9a0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2b9b0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2b9c0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2b9d0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
2b9e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2b9f0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2ba00 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2ba10 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2ba20 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2ba30 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2ba40 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2ba50 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2ba60 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2ba70 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2ba80 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2ba90 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2baa0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2bab0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2bac0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2bad0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2bae0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 20 69 66  ther.** words if
2baf0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2bb00 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2bb10 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2bb20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2bb30 76 65 72 73 69 6f 6e 20 69 73 20 64 6f 6e 65 2e  version is done.
2bb40 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
2bb50 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2bb60 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  .  The .** [SQLI
2bb70 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2bb80 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2bb90 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2bba0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  ned..**.** Pleas
2bbb0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
2bbc0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
2bbd0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
2bbe0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
2bbf0 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  is returned from
2bc00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2bc10 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2bc20 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2bc30 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2bc40 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
2bc50 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
2bc60 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
2bc70 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2bc80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2bc90 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
2bca0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
2bcb0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2bcc0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2bcd0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2bce0 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a 2a  ext16()].  .**.*
2bcf0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2bd00 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2bd10 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2bd20 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2bd30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2bd40 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2bd50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2bd60 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
2bd70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2bd80 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54  **.** {F15103} T
2bd90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2bda0 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2bdb0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2bdc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2bdd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bde0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2bdf0 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20 61 6e 64   into a blob and
2be00 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
2be10 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
2be20 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2be30 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2be40 2a 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b  * {F15106} The [
2be50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2be60 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2be70 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2be80 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2be90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2bea0 20 62 6c 6f 62 20 6f 72 20 73 74 72 69 6e 67 20   blob or string 
2beb0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2bec0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2bed0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2bee0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2bef0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2bf00 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2bf10 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2bf20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2bf30 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2bf40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2bf50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2bf60 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
2bf70 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2bf80 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2bf90 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2bfa0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2bfb0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2bfc0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2bfd0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2bfe0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2bff0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2c000 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2c010 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2c020 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2c030 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2c040 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c050 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2c060 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2c070 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c080 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
2c090 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c0a0 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2c0b0 0a 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65  .** {F15112} The
2c0c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c0d0 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2c0e0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c0f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c110 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c120 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2c130 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2c140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2c150 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2c160 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2c170 20 7b 46 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {F15115} The [s
2c180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2c190 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2c1a0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2c1b0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2c1c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c1d0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2c1e0 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2c1f0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2c200 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2c210 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2c220 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2c230 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38  r..**.** {F15118
2c240 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c250 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2c260 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c270 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c280 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c290 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c2a0 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2c2b0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2c2c0 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2c2d0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2c2e0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2c2f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d  ..**.** {F15121}
2c300 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c310 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2c320 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c330 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c340 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c350 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c360 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2c370 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2c380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2c390 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
2c3a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2c3b0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2c3c0 7b 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71  {F15124} The [sq
2c3d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c3e0 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  16(V)] interface
2c3f0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c400 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2c410 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c420 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2c430 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2c440 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2c450 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2c460 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2c470 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
2c480 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2c490 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c4a0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2c4b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20  .**.** {F15127} 
2c4c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2c4d0 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20  ue_text16be(V)] 
2c4e0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2c4f0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2c500 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2c510 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c520 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
2c530 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2c540 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2c550 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62  aligned UTF-16 b
2c560 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
2c570 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2c580 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c590 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2c5a0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30  g..**.** {F15130
2c5b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c5c0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
2c5d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c5e0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2c5f0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2c600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c610 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2c620 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
2c630 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
2c640 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
2c650 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
2c660 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2c670 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2c680 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2c690 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
2c6a0 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  15133} The [sqli
2c6b0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56  te3_value_type(V
2c6c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2c6d0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
2c6e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2c6f0 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
2c700 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
2c710 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
2c720 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
2c730 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
2c740 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
2c750 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
2c760 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
2c770 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c780 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d  ..**.** {F15136}
2c790 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c7a0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2c7b0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2c7c0 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20  onverts.**      
2c7d0 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74      the [protect
2c7e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c7f0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2c800 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65  either an intege
2c810 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  r or.**         
2c820 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2c830 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61  t value if it ca
2c840 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20  n do so without 
2c850 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  loss of.**      
2c860 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c      information,
2c870 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65   and returns one
2c880 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
2c890 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2c8a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2c8b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2c8c0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2c8d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2c8e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2c8f0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2c900 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c910 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c920 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c930 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e   V after the con
2c940 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e  version attempt.
2c950 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2c960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2c970 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
2c980 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2c990 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
2c9a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2c9b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2c9c0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
2c9d0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
2c9e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
2c9f0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
2ca00 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2ca10 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
2ca20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
2ca30 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
2ca40 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
2ca50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2ca60 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2ca70 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
2ca80 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
2ca90 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
2caa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2cab0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
2cac0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2cad0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2cae0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
2caf0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2cb00 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cb10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2cb20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cb30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2cb40 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
2cb50 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2cb60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2cb70 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
2cb80 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
2cb90 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2cba0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
2cbb0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31  tion Context {F1
2cbc0 36 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6210}.**.** The 
2cbd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2cbe0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2cbf0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2cc00 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  is routine to al
2cc10 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75  locate.** a stru
2cc20 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e  cture for storin
2cc30 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 20 20  g their state.  
2cc40 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
2cc50 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2cc60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2cc70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
2cc80 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
2cc90 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
2cca0 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c  egate, SQLite al
2ccb0 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f  locates nBytes o
2ccc0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 7a 65 72 6f  f memory.** zero
2ccd0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  s that memory, a
2cce0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2ccf0 6e 74 65 72 20 74 6f 20 69 74 2e 0a 2a 2a 20 4f  nter to it..** O
2cd00 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2cd10 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2cd20 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2cd30 74 65 5f 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20  te_context().** 
2cd40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2cd50 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2cd60 69 6e 64 65 78 2c 20 74 68 65 20 73 61 6d 65 20  index, the same 
2cd70 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2cd80 65 64 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ed..** The imple
2cd90 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
2cda0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
2cdb0 6e 20 75 73 65 20 74 68 65 20 72 65 74 75 72 6e  n use the return
2cdc0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
2cdd0 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
2cde0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  .** SQLite autom
2cdf0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2ce00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
2ce10 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
2ce20 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
2ce30 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2ce40 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2ce50 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
2ce60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
2ce70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2ce80 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
2ce90 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
2cea0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
2ceb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2cec0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
2ced0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2cee0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
2cef0 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
2cf00 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2cf10 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2cf20 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2cf30 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2cf40 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
2cf50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2cf60 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2cf70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2cf80 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73 74  16211} The first
2cf90 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
2cfa0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2cfb0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2cfc0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cfd0 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
2cfe0 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72  tance of an aggr
2cff0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28  egate function (
2d000 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2d010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2d020 74 65 78 74 20 43 29 20 63 61 75 73 65 73 20 53  text C) causes S
2d030 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74  QLite to allocat
2d040 69 6f 6e 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ion N bytes of m
2d050 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20  emory,.**       
2d060 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d     zero that mem
2d070 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  ory, and return 
2d080 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d090 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20   allocated.**   
2d0a0 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 2e 0a 2a         memory..*
2d0b0 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66  *.** {F16213} If
2d0c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2d0d0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2d0e0 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
2d0f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
2d100 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2d110 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
2d120 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2d130 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35  0..**.** {F16215
2d140 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
2d150 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2d160 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
2d170 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
2d180 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2d190 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
2d1a0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
2d1b0 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
2d1c0 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
2d1d0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
2d1e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2d1f0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
2d200 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
2d210 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
2d220 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
2d230 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ion..**.** {F162
2d240 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
2d250 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
2d260 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d270 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
2d280 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2d290 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2d2a0 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
2d2b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2d2c0 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
2d2d0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
2d2e0 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
2d2f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d300 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
2d310 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
2d320 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2d330 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2d340 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
2d350 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2d360 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d370 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2d380 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
2d390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d3a0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
2d3b0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
2d3c0 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  40}.**.** The sq
2d3d0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2d3e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d3f0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2d400 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2d410 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2d420 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2d430 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2d440 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2d450 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d460 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2d470 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d480 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2d490 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2d4a0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2d4b0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2d4c0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2d4d0 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  tion. {END}.**.*
2d4e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2d4f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2d500 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2d510 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2d520 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2d530 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2d540 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2d550 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2d560 0a 2a 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65  .** {F16243} The
2d570 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2d580 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ata(C)] interfac
2d590 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2d5a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2d5b0 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72      P pointer fr
2d5c0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2d5d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d5e0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2d5f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2d600 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d610 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
2d620 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
2d630 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
2d640 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
2d650 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2d660 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d680 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43  lite3_context] C
2d690 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2d6a0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
2d6b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2d6c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d6d0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2d6e0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
2d6f0 6e 73 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a  ns {F16250}.**.*
2d700 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
2d710 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2d720 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d730 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2d740 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
2d750 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2d760 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
2d770 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
2d780 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2d790 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d7a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2d7b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d7c0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2d7d0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2d7e0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2d7f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2d800 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2d810 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d820 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35  TS:.**.** {F1625
2d830 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2d840 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2d850 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(C)] interface 
2d860 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2d870 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d880 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    D pointer from
2d890 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2d8a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2d8b0 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2d8c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2d8d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d8e0 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
2d8f0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
2d900 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2d910 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
2d920 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
2d930 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a  sociated with .*
2d940 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d950 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
2d960 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2d970 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2d980 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2d990 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2d9a0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2d9b0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2d9c0 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a  a {F16270}.**.**
2d9d0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2d9e0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2d9f0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2da00 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2da10 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2da20 20 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20   meta-data with 
2da30 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
2da40 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
2da50 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
2da60 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
2da70 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2da80 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
2da90 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
2daa0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
2dab0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
2dac0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
2dad0 74 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61  ted meta-data ma
2dae0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2daf0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2db00 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2db10 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2db20 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2db30 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2db40 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2db50 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2db60 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2db70 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2db80 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64  red as.** meta-d
2db90 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2dba0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
2dbb0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2dbc0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2dbd0 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
2dbe0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
2dbf0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2dc00 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
2dc10 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
2dc20 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2dc30 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
2dc40 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
2dc50 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
2dc60 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
2dc70 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
2dc80 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
2dc90 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  cation..**.** Th
2dca0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2dcb0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2dcc0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2dcd0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 2d  ter to the meta-
2dce0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2dcf0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2dd00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2dd10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2dd20 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2dd30 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2dd40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dd50 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ed function..** 
2dd60 49 66 20 6e 6f 20 6d 65 74 61 2d 64 61 74 61 20  If no meta-data 
2dd70 68 61 73 20 62 65 65 6e 20 65 76 65 72 20 62 65  has been ever be
2dd80 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
2dd90 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
2dda0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
2ddb0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
2ddc0 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2ddd0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 68 61   parameter.** ha
2dde0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
2ddf0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
2de00 73 20 73 65 74 2c 20 74 68 65 6e 20 73 71 6c 69  s set, then sqli
2de10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2de20 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  ).** returns a N
2de30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2de40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
2de50 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2de60 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
2de70 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20 70 6f   meta-data.** po
2de80 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
2de90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
2dea0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 66   the meta-data f
2deb0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2dec0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2ded0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dee0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2def0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2df00 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2df10 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2df20 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2df30 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2df40 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2df50 65 64 2e 20 0a 2a 2a 20 49 66 20 69 74 20 69 73  ed. .** If it is
2df60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2df70 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2df80 65 20 64 65 73 74 72 75 63 74 6f 72 20 0a 2a 2a  e destructor .**
2df90 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2dfa0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2dfb0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2dfc0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2dfd0 0a 2a 2a 20 74 68 65 20 6d 65 74 61 2d 64 61 74  .** the meta-dat
2dfe0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  a when the corre
2dff0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
2e000 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
2e010 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74  ges.** or when t
2e020 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e030 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63   completes, whic
2e040 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
2e050 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
2e060 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20  is free to call 
2e070 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61  the destructor a
2e080 6e 64 20 64 72 6f 70 20 6d 65 74 61 2d 64 61 74  nd drop meta-dat
2e090 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20 70 61 72 61  a on.** any para
2e0a0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
2e0b0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
2e0c0 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75 61  e.  The only gua
2e0d0 72 61 6e 74 65 65 0a 2a 2a 20 69 73 20 74 68 61  rantee.** is tha
2e0e0 74 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  t the destructor
2e0f0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20   will be called 
2e100 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64  before the metad
2e110 61 74 61 20 69 73 0a 2a 2a 20 64 72 6f 70 70 65  ata is.** droppe
2e120 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
2e130 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61 20  tice, meta-data 
2e140 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
2e150 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
2e160 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
2e170 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
2e180 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
2e190 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
2e1a0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
2e1b0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
2e1c0 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
2e1d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e1e0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2e1f0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2e200 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2e210 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2e220 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2e230 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2e240 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20  .**.** {F16272} 
2e250 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
2e260 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69  _auxdata(C,N)] i
2e270 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e280 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
2e290 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61         to metada
2e2a0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2e2b0 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  th the Nth param
2e2c0 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
2e2d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2e2e0 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65       whose conte
2e2f0 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c  xt is C, or NULL
2e300 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
2e310 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2e320 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2e330 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65  with that parame
2e340 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  ter..**.** {F162
2e350 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  74} The [sqlite3
2e360 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
2e370 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,P,D)] interface
2e380 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64   assigns a metad
2e390 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
2e3a0 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65  pointer P to the
2e3b0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
2e3c0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2e3d0 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 0a  on with context.
2e3e0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a  **          C..*
2e3f0 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d 20 53 51  *.** {F16276} SQ
2e400 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
2e410 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2e420 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20  D with a single 
2e430 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  argument.**     
2e440 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74 68       which is th
2e450 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e 74  e metadata point
2e460 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  er P following a
2e470 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20   call to.**     
2e480 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
2e490 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2e4a0 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65 20  D)] when SQLite 
2e4b0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a  ceases to hold.*
2e4c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d  *          the m
2e4d0 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b  etadata..**.** {
2e4e0 46 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20 63  F16277} SQLite c
2e4f0 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65  eases to hold me
2e500 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53 51  tadata for an SQ
2e510 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  L function param
2e520 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eter.**         
2e530 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   when the value 
2e540 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  of that paramete
2e550 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  r changes..**.**
2e560 20 7b 46 31 36 32 37 38 7d 20 57 68 65 6e 20 5b   {F16278} When [
2e570 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e580 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73  ata(C,N,P,D)] is
2e590 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64 65   invoked, the de
2e5a0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20  structor.**     
2e5b0 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20 66       is called f
2e5c0 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65 74  or any prior met
2e5d0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2e5e0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2e5f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2e600 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61 6e      context C an
2e610 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a  d parameter N..*
2e620 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d 20 53 51  *.** {F16279} SQ
2e630 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64  Lite will call d
2e640 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 61  estructors for a
2e650 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20 69  ny metadata it i
2e660 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20  s holding.**    
2e670 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74 69        in a parti
2e680 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64 20  cular [prepared 
2e690 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68 65  statement] S whe
2e6a0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  n either.**     
2e6b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2e6c0 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69  set(S)] or [sqli
2e6d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
2e6e0 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76   is called..*/.v
2e6f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
2e700 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2e710 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2e720 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2e730 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
2e740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2e750 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
2e760 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
2e770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e780 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
2e790 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
2e7a0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20 7b  uctor Behavior {
2e7b0 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10280}.**.** Th
2e7c0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
2e7d0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65  value for the de
2e7e0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2e7f0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2e800 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2e810 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2e820 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2e830 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
2e840 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2e850 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2e860 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2e870 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
2e880 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
2e890 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
2e8a0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
2e8b0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2e8c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2e8d0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a  estroyed.  The .
2e8e0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
2e8f0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
2e900 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2e910 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
2e920 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
2e930 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
2e940 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
2e950 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
2e960 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
2e970 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
2e980 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
2e990 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
2e9a0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
2e9b0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
2e9c0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
2e9d0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
2e9e0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
2e9f0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
2ea00 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
2ea10 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2ea20 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
2ea30 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
2ea40 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
2ea50 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
2ea60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ea70 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
2ea80 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2ea90 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
2eaa0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
2eab0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
2eac0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
2ead0 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F16400}.**.** 
2eae0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2eaf0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
2eb00 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
2eb10 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
2eb20 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
2eb30 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2eb40 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
2eb50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eb60 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2eb70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eb80 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2eb90 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
2eba0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
2ebb0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2ebc0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
2ebd0 63 68 20 6c 69 6b 65 20 74 68 65 20 0a 2a 2a 20  ch like the .** 
2ebe0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2ebf0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2ec00 64 5f 2a 5d 20 66 61 6d 69 6c 79 20 6f 66 20 66  d_*] family of f
2ec10 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 0a 2a 2a  unctions used.**
2ec20 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
2ec30 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
2ec40 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
2ec50 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
2ec60 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 73  fer to the.** [s
2ec70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ec80 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2ec90 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  * documentation]
2eca0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
2ecb0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
2ecc0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2ecd0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
2ece0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2ecf0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2ed00 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2ed10 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2ed20 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
2ed30 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
2ed40 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
2ed50 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
2ed60 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
2ed70 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
2ed80 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
2ed90 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
2eda0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 73 71 6c  ter. .** The sql
2edb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2edc0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2edd0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2ede0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2edf0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2ee00 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2ee10 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2ee20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2ee30 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2ee40 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2ee50 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2ee60 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2ee70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2ee80 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2ee90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2eea0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2eeb0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2eec0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2eed0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2eee0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2eef0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2ef00 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2ef10 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2ef20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ef30 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2ef40 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2ef50 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2ef60 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2ef70 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2ef80 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2ef90 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
2efa0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2efb0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2efc0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2efd0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2efe0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2eff0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f000 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2f010 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2f020 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2f030 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
2f040 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2f050 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2f060 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2f070 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2f080 54 46 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  TF8. SQLite.** i
2f090 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2f0a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2f0b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f0c0 28 29 20 61 73 20 55 54 46 31 36 20 69 6e 20 6e  () as UTF16 in n
2f0d0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
2f0e0 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
2f0f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f100 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f110 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2f120 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f130 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
2f140 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2f150 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
2f160 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
2f170 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
2f180 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2f190 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
2f1a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f1b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2f1c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2f1d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2f1e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2f1f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
2f200 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
2f210 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
2f220 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
2f230 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
2f240 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2f250 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
2f260 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f270 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2f280 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2f290 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
2f2a0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f  utines make a co
2f2b0 70 79 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  py private copy 
2f2c0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2f2d0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2f2e0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2f2f0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2f300 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2f310 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2f320 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2f330 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2f340 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2f350 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  m..** The sqlite
2f360 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2f370 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2f380 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2f390 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2f3a0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2f3b0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2f3c0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2f3d0 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a  n.  By default,.
2f3e0 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ** the error cod
2f3f0 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f  e is SQLITE_ERRO
2f400 52 2e 20 20 41 20 73 75 62 73 65 71 75 65 6e 74  R.  A subsequent
2f410 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
2f420 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2f430 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2f440 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
2f450 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
2f460 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
2f470 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  RROR..**.** The 
2f480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f490 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
2f4a0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 0a  e causes SQLite.
2f4b0 2a 2a 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  ** to throw an e
2f4c0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20  rror indicating 
2f4d0 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
2f4e0 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67   BLOB is to long
2f4f0 0a 2a 2a 20 74 6f 20 72 65 70 72 65 73 65 6e 74  .** to represent
2f500 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  .  The sqlite3_r
2f510 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2f520 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75 73 65  terface.** cause
2f530 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2f540 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 69  w an exception i
2f550 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
2f560 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  he a.** memory a
2f570 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
2f580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2f590 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2f5a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2f5b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2f5c0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2f5d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f5e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2f5f0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2f600 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2f610 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2f620 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
2f630 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f640 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2f650 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2f660 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2f670 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f680 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f690 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2f6a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2f6b0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2f6c0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2f6d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
2f6e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2f6f0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2f700 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2f710 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2f720 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f730 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f740 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
2f750 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f760 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
2f770 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
2f780 2c 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  , .** sqlite3_re
2f790 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2f7a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2f7b0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2f7c0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2f7d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2f7e0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2f7f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f800 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2f810 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2f820 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2f830 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2f840 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2f850 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2f860 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2f870 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2f880 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2f890 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b  y..** SQLite tak
2f8a0 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
2f8b0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
2f8c0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
2f8d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f8e0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2f8f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2f900 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20  terfaces..** If 
2f910 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2f920 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2f930 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2f940 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2f950 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
2f960 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
2f970 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
2f980 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 0a 2a  2nd parameter .*
2f990 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
2f9a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2f9b0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
2f9c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2f9d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f9e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2f9f0 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
2fa00 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
2fa10 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
2fa20 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
2fa30 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
2fa40 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
2fa50 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
2fa60 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
2fa70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
2fa80 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
2fa90 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2faa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2fab0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2fac0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2fad0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2fae0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
2faf0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
2fb00 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
2fb10 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
2fb20 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
2fb30 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
2fb40 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75  ext or blob resu
2fb50 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
2fb60 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
2fb70 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
2fb80 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
2fb90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fbb0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fbc0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fbd0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2fbe0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2fbf0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2fc00 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 73 73  en.** SQLite ass
2fc10 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2fc20 78 74 20 6f 72 20 62 6c 6f 62 20 72 65 73 75 6c  xt or blob resul
2fc30 74 20 69 73 20 63 6f 6e 73 74 61 6e 74 20 73 70  t is constant sp
2fc40 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f 65 73 20  ace and.** does 
2fc50 6e 6f 74 20 63 6f 70 79 20 74 68 65 20 73 70 61  not copy the spa
2fc60 63 65 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  ce or call a des
2fc70 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
2fc80 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2fc90 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2fca0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
2fcb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2fcc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2fcd0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2fce0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
2fcf0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
2fd00 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
2fd10 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
2fd20 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
2fd30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
2fd40 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
2fd50 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
2fd60 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
2fd70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2fd80 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
2fd90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
2fda0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2fdb0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2fdc0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2fdd0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2fde0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fdf0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2fe00 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2fe10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fe20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2fe30 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2fe40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2fe50 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2fe60 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2fe70 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2fe80 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2fe90 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2fea0 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  o that [sqlite3_
2feb0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
2fec0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2fed0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
2fee0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
2fef0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2ff00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
2ff10 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
2ff20 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65  arm..** A [prote
2ff30 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ff40 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
2ff50 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
2ff60 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
2ff70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ff80 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
2ff90 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
2ffa0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
2ffb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ffc0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
2ffd0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
2ffe0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
2fff0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
30000 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
30010 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
30020 65 6e 74 20 74 68 72 65 61 64 20 0a 2a 2a 20 74  ent thread .** t
30030 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
30040 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
30050 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30060 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
30070 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
30080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
30090 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
300a0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
300b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
300c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  NTS:.**.** {F164
300d0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
300e0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
300f0 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
30100 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
30110 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20 5b  * {F16406} The [
30120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
30130 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
30140 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30150 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30160 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30170 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30180 20 61 20 62 6c 6f 62 20 74 68 61 74 20 69 73 20   a blob that is 
30190 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
301a0 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
301b0 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
301c0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
301d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20 54  **.** {F16409} T
301e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
301f0 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
30200 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30210 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30220 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
30230 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30240 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
30250 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
30260 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54 68  *.** {F16412} Th
30270 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30280 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
30290 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
302a0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
302b0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
302c0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
302d0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
302e0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
302f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
30300 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
30310 20 55 54 46 38 20 65 72 72 6f 72 20 6d 65 73 73   UTF8 error mess
30320 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  age copied from 
30330 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20  V up to the.**  
30340 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65          first ze
30350 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c  ro byte or until
30360 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61   N bytes are rea
30370 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
30380 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
30390 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
303a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43  result_error16(C
303b0 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
303c0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
303d0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
303e0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
303f0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
30400 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
30410 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
30420 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
30430 5d 20 61 6e 64 20 61 20 55 54 46 31 36 20 6e 61  ] and a UTF16 na
30440 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
30450 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
30460 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
30470 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
30480 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
30490 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
304a0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
304b0 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
304c0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
304d0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38 7d 20 54  **.** {F16418} T
304e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
304f0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
30500 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
30510 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
30520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
30530 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
30540 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
30550 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
30560 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
30570 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
30580 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
30590 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
305a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
305b0 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
305c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
305d0 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
305e0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
305f0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
30600 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
30610 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
30620 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
30630 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
30640 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
30650 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
30660 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
30670 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
30680 7b 46 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {F16424} The [sq
30690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
306a0 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
306b0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
306c0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
306d0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
306e0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
306f0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
30700 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
30710 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
30720 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
30730 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
30740 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nged..**.** {F16
30750 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
30760 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
30770 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30780 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
30790 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
307a0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
307b0 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
307c0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
307d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 30 7d  ..**.** {F16430}
307e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
307f0 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
30800 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
30810 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
30820 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
30830 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
30840 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
30850 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
30860 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33 7d 20 54  **.** {F16433} T
30870 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30880 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
30890 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
308a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
308b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
308c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
308d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
308e0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
308f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
30900 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
30910 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30920 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30930 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30940 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
30950 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  F8 string.**    
30960 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68        V up to th
30970 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
30980 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
30990 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
309a0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
309b0 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
309c0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
309d0 7b 46 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71  {F16439} The [sq
309e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
309f0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  t16(C,V,N,D)] in
30a00 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30a10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30a20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30a30 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30a40 20 74 68 65 20 55 54 46 31 36 20 6e 61 74 69 76   the UTF16 nativ
30a50 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
30a60 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
30a70 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
30a80 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
30a90 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
30aa0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
30ab0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
30ac0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
30ad0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
30ae0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30af0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
30b00 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
30b10 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30b20 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30b30 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30b40 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
30b50 20 55 54 46 31 36 20 62 69 67 2d 65 6e 64 69 61   UTF16 big-endia
30b60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
30b70 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
30b80 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
30b90 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
30ba0 69 73 20 6e 65 67 61 74 69 76 65 20 6f 72 20 74  is negative or t
30bb0 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
30bc0 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
30bd0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
30be0 2a 20 7b 46 31 36 34 34 35 7d 20 54 68 65 20 5b  * {F16445} The [
30bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30c00 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
30c10 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30c20 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30c30 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30c40 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30c50 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6c  o be the UTF16 l
30c60 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
30c70 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
30c80 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
30c90 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a  t zero if N is.*
30ca0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 67 61 74  *          negat
30cb0 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73 74  ive or the first
30cc0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
30cd0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
30ce0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34  ve..**.** {F1644
30cf0 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
30d00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56  result_value(C,V
30d10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30d20 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
30d30 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
30d40 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
30d50 74 6f 20 62 65 20 5b 75 6e 70 72 6f 74 65 63 74  to be [unprotect
30d60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30d70 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
30d80 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
30d90 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16451} The [sqli
30da0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
30db0 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(C,N)] interf
30dc0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30dd0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30de0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30df0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
30e00 4e 2d 62 79 74 65 20 62 6c 6f 62 20 6f 66 20 61  N-byte blob of a
30e10 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20  ll zeros..**.** 
30e20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71  {F16454} The [sq
30e30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30e40 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  or()] and [sqlit
30e50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30e60 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
30e70 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
30e80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
30e90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
30ea0 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a  trings before.**
30eb0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30ec0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ing..**.** {F164
30ed0 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  57} If the D des
30ee0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
30ef0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
30f00 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
30f10 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
30f20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30f30 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
30f40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30f50 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
30f60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
30f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30f80 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
30f90 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
30fa0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
30fb0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
30fc0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
30fd0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
30fe0 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  TIC].**         
30ff0 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63   then no destruc
31000 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c  tor is ever call
31010 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65  ed on the pointe
31020 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a  r V and SQLite.*
31030 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d  *          assum
31040 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d  es that V is imm
31050 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  utable..**.** {F
31060 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20  16460} If the D 
31070 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
31080 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
31090 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
310a0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
310b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
310c0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
310d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
310e0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
310f0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
31100 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
31110 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
31120 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
31130 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
31140 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
31150 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
31160 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20  onstant.**      
31170 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e      [SQLITE_TRAN
31180 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
31190 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
311a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
311b0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
311c0 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61  nt of V and reta
311d0 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a  ins the copy..**
311e0 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66 20  .** {F16463} If 
311f0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
31200 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
31210 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31220 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
31230 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
31240 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
31250 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
31260 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31270 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
31280 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
31290 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
312a0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
312b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
312c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
312d0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
312e0 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65   some value othe
312f0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
31300 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73     the constants
31310 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
31320 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41   and [SQLITE_TRA
31330 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 0a 2a 2a  NSIENT] then .**
31340 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
31350 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
31360 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
31370 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
31380 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
31390 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
313a0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
313b0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
313c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
313d0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
313e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
313f0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
31400 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
31410 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31420 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
31430 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
31440 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
31450 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
31460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31470 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
31480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31490 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
314a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
314b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
314c0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
314d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
314e0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
314f0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
31500 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31510 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
31520 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
31530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31540 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
31550 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
31560 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31570 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
31580 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
31590 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
315a0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
315b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
315c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
315d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
315e0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
315f0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
31600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31610 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31620 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
31630 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
31640 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
31650 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31660 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
31670 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31680 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
31690 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
316a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
316b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
316c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
316d0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
316e0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
316f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31700 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
31710 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
31720 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
31730 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
31740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
31750 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
31760 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
31770 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
31780 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
31790 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
317a0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
317b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
317c0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
317d0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46  ing Sequences {F
317e0 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16600}.**.** The
317f0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
31800 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
31810 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
31820 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
31830 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65  sqlite3*] handle
31840 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
31850 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31860 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  . .**.** The nam
31870 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
31880 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
31890 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
318a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
318b0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
318c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
318d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
318e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
318f0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
31900 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
31910 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31920 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
31930 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
31940 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
31950 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
31960 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
31970 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
31980 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
31990 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
319a0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
319b0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
319c0 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
319d0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
319e0 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
319f0 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
31a00 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
31a10 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
31a20 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
31a30 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
31a40 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
31a50 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  6 little-endian 
31a60 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
31a70 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
31a80 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
31a90 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
31aa0 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
31ab0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
31ac0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
31ad0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
31ae0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
31af0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
31b00 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
31b10 20 6f 66 20 55 54 46 31 36 20 69 6e 20 74 68 65   of UTF16 in the
31b20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
31b30 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63  er of the host c
31b40 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  omputer..**.** A
31b50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31b60 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
31b70 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
31b80 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
31b90 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
31ba0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
31bb0 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
31bc0 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
31bd0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
31be0 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
31bf0 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
31c00 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a  l it anymore)..*
31c10 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20  * Each time the 
31c20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 73  application.** s
31c30 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
31c40 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
31c50 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
31c60 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
31c70 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 66  ssed as.** the f
31c80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
31c90 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31ca0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a  _collation() or.
31cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
31cc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20  e_collation16() 
31cd0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
31ce0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
31cf0 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
31d00 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
31d10 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
31d20 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
31d30 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
31d40 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
31d50 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
31d60 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
31d70 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
31d80 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
31d90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
31da0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
31db0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
31dc0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
31dd0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
31de0 7d 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  } The applicatio
31df0 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
31e00 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
31e10 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
31e20 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
31e30 6f 73 69 74 69 76 65 20 69 66 0a 2a 2a 20 74 68  ositive if.** th
31e40 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
31e50 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
31e60 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
31e70 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
31e80 64 0a 2a 2a 20 73 74 72 69 6e 67 2e 20 69 2e 65  d.** string. i.e
31e90 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
31ea0 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ING2)..**.** The
31eb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31ec0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
31ed0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
31ee0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31ef0 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  on().** except t
31f00 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
31f10 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
31f20 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
31f30 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
31f40 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20  collation.  The 
31f50 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
31f60 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
31f70 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
31f80 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
31f90 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
31fa0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
31fb0 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
31fc0 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
31fd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31fe0 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43  ation_v2()..** C
31ff0 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65  ollations are de
32000 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a 2a 20  stroyed when.** 
32010 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
32020 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
32030 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
32040 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
32050 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77 68 65  ctions.** or whe
32060 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d  n the [sqlite3*]
32070 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
32080 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
32090 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
320a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
320b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
320c0 36 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  603} A successfu
320d0 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a  l call to the.**
320e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
320f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32100 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
32110 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  ,D)] interface.*
32120 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
32130 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20 46 20  ters function F 
32140 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  as the compariso
32150 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65 64 20  n function used 
32160 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  to.**          i
32170 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69  mplement collati
32180 6f 6e 20 58 20 6f 6e 20 5b 64 61 74 61 62 61 73  on X on [databas
32190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
321a0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
321b0 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
321c0 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
321d0 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69  ** {F16604} SQLi
321e0 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
321f0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
32200 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
32210 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32220 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
32230 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
32240 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
32250 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
32260 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
32270 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
32280 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
32290 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
322a0 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
322b0 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
322c0 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
322d0 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63  .** {F16606} Suc
322e0 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
322f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32300 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
32310 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
32320 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
32330 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
32340 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
32350 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
32360 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
32370 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
32380 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 54  **.** {F16609} T
32390 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
323a0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
323b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
323c0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
323d0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
323e0 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
323f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
32400 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
32410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
32420 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32430 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
32440 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  Lite..**.** {F16
32450 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
32460 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
32470 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
32480 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
32490 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {F16615} A col
324a0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
324b0 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
324c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
324d0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
324e0 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
324f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
32500 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  se()]..**.** {F1
32510 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
32520 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
32530 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32540 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
32550 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
32560 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
32570 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
32580 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
32590 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
325a0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
325b0 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
325c0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
325d0 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  f F..**.** {F166
325e0 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
325f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32600 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
32610 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
32620 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
32630 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
32640 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32650 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
32660 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
32670 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
32680 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
32690 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
326a0 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {F16624} Foll
326b0 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
326c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
326d0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
326e0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
326f0 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
32700 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
32710 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
32720 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
32730 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
32740 69 6f 6e 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ions on [databas
32750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
32760 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
32770 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
32780 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
32790 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  g sequence name 
327a0 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37  X..**.** {F16627
327b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
327c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
327d0 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f  6(B,X,E,P,F)] wo
327e0 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  rks the same.** 
327f0 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
32800 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32810 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
32820 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
32830 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
32840 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  llation name X i
32850 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20  s understood as 
32860 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
32870 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
32880 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20          instead 
32890 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  of UTF-8..**.** 
328a0 7b 46 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75  {F16630} When mu
328b0 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f  ltiple compariso
328c0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  n functions are 
328d0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68  available for th
328e0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
328f0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
32900 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68  uence, SQLite ch
32910 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68  ooses the one wh
32920 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ose text encodin
32930 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  g.**          re
32940 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
32950 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65   amount of conve
32960 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64  rsion from the d
32970 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20  efault.**       
32980 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67     text encoding
32990 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
329a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
329b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
329c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
329d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
329e0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
329f0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
32a00 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
32a10 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
32a20 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
32a30 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
32a40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32a50 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
32a60 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
32a70 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
32a80 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
32a90 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
32aa0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
32ab0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
32ac0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
32ad0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
32ae0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
32af0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32b00 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
32b10 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
32b20 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
32b30 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32b40 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
32b50 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
32b60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
32b70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
32b80 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
32b90 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
32ba0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
32bb0 73 20 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a  s {F16700}.**.**
32bc0 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
32bd0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
32be0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
32bf0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
32c00 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
32c10 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
32c20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
32c30 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
32c40 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
32c50 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
32c60 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  to be called whe
32c70 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
32c80 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
32c90 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75  uence is.** requ
32ca0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ired..**.** If t
32cb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
32cc0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
32cd0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
32ce0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
32cf0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
32d00 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
32d10 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
32d20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32d30 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
32d40 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
32d50 2d 38 2e 20 7b 46 31 36 37 30 33 7d 20 49 66 20  -8. {F16703} If 
32d60 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
32d70 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
32d80 75 73 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a  used, the names.
32d90 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 61 73  ** are passed as
32da0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
32db0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
32dc0 72 64 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20  rder. A call to 
32dd0 65 69 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69  either.** functi
32de0 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20  on replaces any 
32df0 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63  existing callbac
32e00 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  k..**.** When th
32e10 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
32e20 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
32e30 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
32e40 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
32e50 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
32e60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
32e70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
32e80 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
32e90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
32ea0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
32eb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
32ec0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68  he database.** h
32ed0 61 6e 64 6c 65 2e 20 20 54 68 65 20 74 68 69 72  andle.  The thir
32ee0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
32ef0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
32f00 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
32f10 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
32f20 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
32f30 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
32f40 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66  t.** desirable f
32f50 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
32f60 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75  tion sequence fu
32f70 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
32f80 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
32f90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32fa0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
32fb0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
32fc0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
32fd0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
32fe0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
32ff0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
33000 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
33010 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
33020 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33030 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
33040 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
33050 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
33060 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33070 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
33080 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
33090 0a 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73  .** {F16702} A s
330a0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
330b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
330c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c  tion_needed(D,P,
330d0 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F)].**          
330e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  or [sqlite3_coll
330f0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44  ation_needed16(D
33100 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a  ,P,F)] causes.**
33110 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
33120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33130 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20  on] D to invoke 
33140 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20  callback F with 
33150 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
33160 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68    parameter P wh
33170 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20  enever it needs 
33180 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  a comparison fun
33190 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20  ction for a.**  
331a0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
331b0 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20  g sequence that 
331c0 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77  it does not know
331d0 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   about..**.** {F
331e0 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63  16704} Each succ
331f0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
33200 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33210 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a  n_needed()] or.*
33220 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33230 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33240 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69  eded16()] overri
33250 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  des the callback
33260 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
33270 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
33280 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
33290 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69  nnection] by pri
332a0 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68  or calls to eith
332b0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
332c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
332d0 7b 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d  {F16706} The nam
332e0 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74  e of the request
332f0 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ed collating fun
33300 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20  ction passed in 
33310 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33320 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
33330 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
33340 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65   in UTF-8 if the
33350 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
33360 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74        was regist
33370 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
33380 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33390 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  eded()] and.**  
333a0 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54          is in UT
333b0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
333c0 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61   order if the ca
333d0 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20  llback was.**   
333e0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
333f0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
33400 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33410 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a  d16()]..**.** .*
33420 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
33430 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
33440 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
33450 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
33460 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
33470 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
33480 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
33490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
334a0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
334b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
334c0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
334d0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
334e0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
334f0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
33500 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
33510 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
33520 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
33530 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
33540 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
33550 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
33560 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
33570 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
33580 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
33590 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
335a0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
335b0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
335c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
335d0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
335e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
335f0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
33600 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
33610 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
33620 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
33630 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
33640 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
33650 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
33660 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
33670 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
33680 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
33690 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
336a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
336b0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
336c0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
336d0 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
336e0 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
336f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
33700 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
33710 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
33720 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
33730 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
33740 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
33750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
33760 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
33770 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
33780 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
33790 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
337a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
337b0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
337c0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
337d0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
337e0 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e  API3REF:  Suspen
337f0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
33800 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31  A Short Time {F1
33810 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0530}.**.** The 
33820 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
33830 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73  function.** caus
33840 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
33850 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
33860 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
33870 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
33880 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
33890 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
338a0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
338b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
338c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
338d0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
338e0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
338f0 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  th .** milliseco
33900 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
33910 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
33920 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
33930 64 20 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20  d up to .** the 
33940 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
33950 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
33960 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
33970 65 65 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a  eep actually .**
33980 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
33990 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
339a0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
339b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
339c0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
339d0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
339e0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
339f0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
33a00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
33a10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
33a20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
33a30 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d  :.**.** {F10533}
33a40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
33a50 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
33a60 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
33a70 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
33a80 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
33a90 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
33aa0 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
33ab0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
33ac0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
33ad0 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
33ae0 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
33af0 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
33b00 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
33b10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d  ..**.** {F10536}
33b20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
33b30 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
33b40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
33b50 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
33b60 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
33b70 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
33b80 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
33b90 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
33ba0 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
33bb0 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
33bc0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
33bd0 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
33be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
33bf0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
33c00 43 41 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20  CAPI3REF:  Name 
33c10 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
33c20 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
33c30 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a  Files {F10310}.*
33c40 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
33c50 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
33c60 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
33c70 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
33c80 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
33c90 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
33ca0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
33cb0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
33cc0 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
33cd0 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
33ce0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
33cf0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
33d00 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
33d10 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  .** is NULL poin
33d20 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
33d30 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66   does a search f
33d40 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
33d50 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66  e temporary.** f
33d60 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
33d70 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
33d80 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
33d90 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
33da0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
33db0 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65  ection.** has be
33dc0 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69  en opened.  It i
33dd0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
33de0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
33df0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
33e00 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
33e10 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
33e20 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
33e30 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
33e40 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
33e50 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65  been call and re
33e60 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74  main unchanged t
33e70 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51  hereafter..*/.SQ
33e80 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
33e90 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
33ea0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
33eb0 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74   CAPI3REF:  Test
33ec0 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44   To See If The D
33ed0 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75  atabase Is In Au
33ee0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b  to-Commit Mode {
33ef0 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12930}.**.** Th
33f00 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
33f10 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
33f20 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
33f30 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
33f40 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
33f50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33f60 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
33f70 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
33f80 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
33f90 6c 79 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ly.   Autocommit
33fa0 20 6d 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62   mode is on.** b
33fb0 79 20 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f  y default.  Auto
33fc0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
33fd0 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45  isabled by a [BE
33fe0 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  GIN] statement..
33ff0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
34000 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
34010 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
34020 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
34030 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
34040 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
34050 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
34060 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
34070 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
34080 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72  transactions (er
34090 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
340a0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
340b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a  QLITE_IOERR], .*
340c0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
340d0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
340e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
340f0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
34100 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
34110 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
34120 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
34130 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
34140 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
34150 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f  t if SQLite auto
34160 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
34170 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
34180 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
34190 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
341a0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
341b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
341c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31  S:.**.** {F12931
341d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
341e0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29  et_autocommit(D)
341f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
34200 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
34210 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
34220 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   if the [databas
34230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
34240 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
34250 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20  autocommit.**   
34260 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73         mode, res
34270 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
34280 20 7b 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f   {F12932} Autoco
34290 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
342a0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
342b0 2a 20 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63  * {F12933} Autoc
342c0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
342d0 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  sabled by a succ
342e0 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73  essful [BEGIN] s
342f0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
34300 7b 46 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d  {F12934} Autocom
34310 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  mit mode is enab
34320 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
34330 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  ful [COMMIT] or 
34340 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20  [ROLLBACK].**   
34350 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
34360 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ..** .**.** LIMI
34370 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20  TATIONS:.***.** 
34380 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74  {U12936} If anot
34390 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
343a0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
343b0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
343c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
343d0 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20       connection 
343e0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
343f0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
34400 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
34410 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
34420 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34430 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
34440 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c  t_autocommit(sql
34450 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
34460 41 50 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54  API3REF:  Find T
34470 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
34480 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
34490 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31   Statement {F131
344a0 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20}.**.** The sq
344b0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
344c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
344d0 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65  urns the [sqlite
344e0 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
344f0 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a  dle to which a.*
34500 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
34510 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
34520 2a 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  ** The database 
34530 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20  handle returned 
34540 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
34550 6e 64 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73  ndle.** is the s
34560 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
34570 64 6c 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  dle that was.** 
34580 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
34590 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
345a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
345b0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
345c0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 75 73 65  .** that was use
345d0 64 20 74 6f 20 63 72 65 61 74 65 20 74 68 65 20  d to create the 
345e0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
345f0 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
34600 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
34610 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54  **.** {F13123} T
34620 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68  he [sqlite3_db_h
34630 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66  andle(S)] interf
34640 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
34650 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
34660 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61    to the [databa
34670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
34680 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
34690 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
346a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
346b0 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  S..*/.sqlite3 *s
346c0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
346d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
346e0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
346f0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
34700 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
34710 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
34720 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12950}.**.** The
34730 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
34740 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
34750 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
34760 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
34770 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
34780 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
34790 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
347a0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
347b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
347c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
347d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
347e0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
347f0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
34800 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
34810 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
34820 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
34830 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
34840 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
34850 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
34860 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
34870 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
34880 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
34890 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
348a0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
348b0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
348c0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
348d0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
348e0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
348f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
34900 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
34910 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
34920 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a  passed through.*
34930 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
34940 6b 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  k.  If the callb
34950 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20  ack on a commit 
34960 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a  hook function .*
34970 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
34980 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ro, then the com
34990 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
349a0 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
349b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
349c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
349d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
349e0 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
349f0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
34a00 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
34a10 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
34a20 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  d..**.** Registe
34a30 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
34a40 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
34a50 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
34a60 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
34a70 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
34a80 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
34a90 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
34aa0 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  en .** rolled ba
34ab0 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
34ac0 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
34ad0 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
34ae0 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
34af0 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
34b00 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
34b10 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
34b20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
34b30 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
34b40 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
34b50 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
34b60 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
34b70 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
34b80 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
34b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34ba0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
34bb0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
34bc0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
34bd0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
34be0 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
34bf0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
34c00 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
34c10 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
34c20 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
34c30 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
34c40 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  o>.**.** These a
34c50 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  re experimental 
34c60 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64 20 61  interfaces and a
34c70 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
34c80 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ange..**.** INVA
34c90 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
34ca0 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  12951} The [sqli
34cb0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
34cc0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
34cd0 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
34ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
34cf0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
34d00 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
34d10 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
34d20 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
34d30 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
34d40 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74   commits on [dat
34d50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34d60 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
34d70 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  52} The [sqlite3
34d80 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
34d90 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
34da0 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
34db0 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
34dc0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
34dd0 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
34de0 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20  e same .**      
34df0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
34e00 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f  nnection ] D , o
34e10 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
34e20 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  rst call.**     
34e30 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69       for a parti
34e40 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20  cular [database 
34e50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
34e60 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61  *.** {F12953} Ea
34e70 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
34e80 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
34e90 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
34ea0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
34eb0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
34ec0 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
34ed0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d  ..**.** {F12954}
34ee0 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
34ef0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
34f00 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
34f10 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
34f20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
34f30 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
34f40 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64  back is canceled
34f50 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
34f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
34f70 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
34f80 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
34f90 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ts..**.** {F1295
34fa0 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
34fb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
34fc0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
34fd0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
34fe0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
34ff0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
35000 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
35010 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
35020 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
35030 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
35040 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
35050 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
35060 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
35070 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
35080 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
35090 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
350a0 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
350b0 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64  rolls back on [d
350c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
350d0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
350e0 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
350f0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
35100 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
35110 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
35120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
35130 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
35140 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
35150 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20  h the same .**  
35160 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
35170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44  e connection ] D
35180 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68   , or NULL on th
35190 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20  e first call.** 
351a0 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70           for a p
351b0 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62  articular [datab
351c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
351d0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33  D..**.** {F12963
351e0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
351f0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
35200 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69  _hook()] overwri
35210 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  tes the callback
35220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
35230 69 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72  istered by prior
35240 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   calls..**.** {F
35250 31 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20  12964} If the F 
35260 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
35270 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
35280 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
35290 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
352a0 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b  hen the rollback
352b0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
352c0 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e  s canceled and n
352d0 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  o callback.**   
352e0 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
352f0 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
35300 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e  tion rolls back.
35310 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35320 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
35330 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
35340 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
35350 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
35360 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
35370 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
35380 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
35390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
353a0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
353b0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
353c0 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a  s {F12970}.**.**
353d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
353e0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
353f0 66 61 63 65 0a 2a 2a 20 72 65 67 69 73 74 65 72  face.** register
35400 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
35410 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64  ction with the d
35420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35430 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  on identified by
35440 20 74 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61   the .** first a
35450 72 67 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e  rgument to be in
35460 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
35470 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
35480 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
35490 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
354a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
354b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
354c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f  this function fo
354d0 72 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64  r the same .** d
354e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
354f0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
35500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
35510 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
35520 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
35530 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
35540 6b 65 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f  ke when a .** ro
35550 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
35560 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
35570 64 2e 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  d. .** The first
35580 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
35590 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
355a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
355b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
355c0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
355d0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ook()..** The se
355e0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a  cond callback .*
355f0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  * argument is on
35600 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
35610 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
35620 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
35630 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70  _UPDATE],.** dep
35640 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
35650 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
35660 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
35670 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
35680 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
35690 20 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75   .** fourth argu
356a0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
356b0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
356c0 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 64 61  inters to the da
356d0 74 61 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74  tabase and .** t
356e0 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
356f0 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
35700 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69  d row..** The fi
35710 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
35720 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68  ameter is .** th
35730 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72  e rowid of the r
35740 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61  ow..** In the ca
35750 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
35760 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
35770 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65  id after .** the
35780 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
35790 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
357a0 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
357b0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
357c0 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
357d0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
357e0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
357f0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
35800 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
35810 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
35820 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
35830 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
35840 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
35850 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
35860 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
35870 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
35880 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
35890 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31  S:.**.** {F12971
358a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
358b0 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
358c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  )] interface cau
358d0 73 65 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ses callback.** 
358e0 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
358f0 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
35900 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61 72  d with first par
35910 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76 65  ameter P wheneve
35920 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
35930 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64  table row is mod
35940 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c  ified, inserted,
35950 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a   or deleted on.*
35960 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
35970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35980 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37   D..**.** {F1297
35990 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
359a0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
359b0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
359c0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a  turns the value.
359d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50  **          of P
359e0 20 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75   for the previou
359f0 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61  s call on the sa
35a00 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
35a10 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20  nection] D,.**  
35a20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
35a30 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 63 61  for the first ca
35a40 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  ll..**.** {F1297
35a50 35 7d 20 49 66 20 74 68 65 20 75 70 64 61 74 65  5} If the update
35a60 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46   hook callback F
35a70 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64   in [sqlite3_upd
35a80 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
35a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
35aa0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f  NULL then the no
35ab0 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b   update callback
35ac0 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a  s are made..**.*
35ad0 2a 20 7b 46 31 32 39 37 37 7d 20 45 61 63 68 20  * {F12977} Each 
35ae0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35af0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
35b00 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70  ,P)] overrides p
35b10 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  rior calls.**   
35b20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 73 61         to the sa
35b30 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20  me interface on 
35b40 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
35b50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
35b60 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 39 7d  ..**.** {F12979}
35b70 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
35b80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
35b90 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
35ba0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a  ternal system.**
35bb0 20 20 20 20 20 20 20 20 20 20 74 61 62 6c 65 73            tables
35bc0 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f   such as sqlite_
35bd0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
35be0 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d  e_sequence are m
35bf0 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  odified..**.** {
35c00 46 31 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f  F12981} The seco
35c10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
35c20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62  the update callb
35c30 61 63 6b 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ack .**         
35c40 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
35c50 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
35c60 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b  ITE_DELETE] or [
35c70 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a  SQLITE_UPDATE],.
35c80 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 70 65  **          depe
35c90 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
35ca0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
35cb0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ed the callback 
35cc0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
35cd0 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68  *.** {F12983} Th
35ce0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
35cf0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
35d00 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
35d10 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a  tain pointers.**
35d20 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72            to zer
35d30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
35d40 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 63 68  -8 strings which
35d50 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f   are the names o
35d60 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
35d70 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74    database and t
35d80 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 65 69  able that is bei
35d90 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20  ng updated...** 
35da0 7b 46 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e  {F12985} The fin
35db0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
35dc0 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77  meter is the row
35dd0 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66  id of the row af
35de0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
35df0 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72  the change occur
35e00 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
35e10 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
35e20 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35e30 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
35e40 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
35e50 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
35e60 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
35e70 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
35e80 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
35e90 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
35ea0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20  red Pager Cache 
35eb0 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10330}.**.** T
35ec0 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
35ed0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
35ee0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
35ef0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
35f00 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
35f10 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
35f20 62 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69  between connecti
35f30 6f 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ons to the same 
35f40 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61  database..** Sha
35f50 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
35f60 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
35f70 69 73 20 74 72 75 65 20 61 6e 64 20 64 69 73 61  is true and disa
35f80 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
35f90 6d 65 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65  ment.** is false
35fa0 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68  ..**.** Cache sh
35fb0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
35fc0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a   and disabled.**
35fd0 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
35fe0 72 6f 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68  rocess. {END} Th
35ff0 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
36000 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
36010 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e  ion 3.5.0..** In
36020 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20   prior versions 
36030 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61 72 69  of SQLite, shari
36040 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65  ng was.** enable
36050 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
36060 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65  r each thread se
36070 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
36080 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
36090 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
360a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
360b0 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
360c0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
360d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
360e0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
360f0 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
36100 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
36110 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62  * Existing datab
36120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
36130 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65  continue use the
36140 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a   sharing mode.**
36150 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66   that was in eff
36160 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20  ect at the time 
36170 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64  they were opened
36180 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20  ..**.** Virtual 
36190 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65  tables cannot be
361a0 20 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61   used with a sha
361b0 72 65 64 20 63 61 63 68 65 2e 20 20 20 57 68 65  red cache.   Whe
361c0 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  n shared.** cach
361d0 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68  e is enabled, th
361e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
361f0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20  e_module()] API 
36200 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
36210 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
36220 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  es will always r
36230 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
36240 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
36250 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
36260 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
36270 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e   cache was.** en
36280 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
36290 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  d successfully. 
362a0 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   An [error code]
362b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
362c0 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
362d0 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
362e0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
362f0 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d  ault. But this m
36300 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a  ight change in.*
36310 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  * future release
36320 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70  s of SQLite.  Ap
36330 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
36340 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65  care about share
36350 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69  d.** cache setti
36360 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74  ng should set it
36370 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a   explicitly..**.
36380 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36390 2a 20 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20 41  * .** {F10331} A
363a0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
363b0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
363c0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
363d0 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20  _cache(B)].**   
363e0 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62         will enab
363f0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68  le or disable sh
36400 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20  ared cache mode 
36410 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75 65  for any subseque
36420 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
36430 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
36440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
36450 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
36460 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33  ss..**.** {F1033
36470 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20 63  6} When shared c
36480 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
36490 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
364a0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a  eate_module()].*
364b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
364c0 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  face will always
364d0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
364e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d  ..**.** {F10337}
364f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
36500 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
36510 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(B)] interface 
36520 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
36530 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20      [SQLITE_OK] 
36540 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
36550 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
36560 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66  isabled successf
36570 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ully..**.** {F10
36580 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 68  339} Shared cach
36590 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
365a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74   default..*/.int
365b0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
365c0 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
365d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
365e0 45 46 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20  EF:  Attempt To 
365f0 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
36600 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F17340}.**.** 
36610 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
36620 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
36630 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
36640 74 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74  to.** free N byt
36650 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
36660 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
36670 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
36680 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
36690 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
366a0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
366b0 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72  ry. {END}  Memor
366c0 79 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63  y used.** to cac
366d0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
366e0 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
366f0 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
36700 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e  xample of.** non
36710 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
36720 79 2e 20 20 53 71 6c 69 74 65 33 5f 72 65 6c 65  y.  Sqlite3_rele
36730 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
36740 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
36750 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
36760 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63  ally freed, whic
36770 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
36780 6f 72 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  or less.** than 
36790 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
367a0 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  sted..**.** INVA
367b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
367c0 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  17341} The [sqli
367d0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
367e0 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ry(N)] interface
367f0 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20   attempts to.** 
36800 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e 20           free N 
36810 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65  bytes of heap me
36820 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
36830 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
36840 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  al.**          m
36850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
36860 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  s held by the da
36870 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a  tabase library..
36880 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54  **.** {F16342} T
36890 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  he [sqlite3_rele
368a0 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72  ase_memory(N)] r
368b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
368c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
368d0 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
368e0 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67  freed, which mig
368f0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
36900 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
36910 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
36920 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74  equested..*/.int
36930 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
36940 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
36950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
36960 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
36970 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37  n Heap Size {F17
36980 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  350}.**.** The s
36990 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
369a0 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
369b0 63 65 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20 22  ce.** places a "
369c0 73 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74  soft" limit on t
369d0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
369e0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
369f0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a  y be allocated.*
36a00 2a 20 62 79 20 53 51 4c 69 74 65 2e 20 49 66 20  * by SQLite. If 
36a10 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
36a20 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
36a30 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75  ted .** that wou
36a40 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73 6f  ld exceed the so
36a50 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b  ft heap limit, [
36a60 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36a70 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20  memory()] is.** 
36a80 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d  invoked one or m
36a90 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
36aa0 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
36ab0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
36ac0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65  ation.** is made
36ad0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69  ..**.** The limi
36ae0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
36af0 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 0a 2a  t", because if.*
36b00 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
36b10 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e  se_memory()] can
36b20 6e 6f 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66  not.** free suff
36b30 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f  icient memory to
36b40 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d   prevent the lim
36b50 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78  it from being ex
36b60 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d  ceeded,.** the m
36b70 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
36b80 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68  ed anyway and th
36b90 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  e current operat
36ba0 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a  ion proceeds..**
36bb0 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f  .** A negative o
36bc0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
36bd0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
36be0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
36bf0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
36c00 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
36c10 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
36c20 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
36c30 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
36c40 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65  xhausted..** The
36c50 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
36c60 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
36c70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
36c80 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  **.** SQLite mak
36c90 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
36ca0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
36cb0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
36cc0 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
36cd0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
36ce0 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
36cf0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
36d00 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
36d10 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
36d20 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
36d30 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
36d40 69 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64  it is .** called
36d50 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
36d60 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
36d70 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
36d80 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
36d90 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
36da0 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
36db0 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
36dc0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
36dd0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
36de0 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
36df0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
36e00 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
36e10 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
36e20 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
36e30 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
36e40 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
36e50 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
36e60 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
36e70 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
36e80 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
36e90 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
36ea0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
36eb0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
36ec0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
36ed0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
36ee0 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
36ef0 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
36f00 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
36f10 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
36f20 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
36f30 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
36f40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36f50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d  :.**.** {F16351}
36f60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
36f70 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
36f80 5d 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63  ] interface plac
36f90 65 73 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a  es a soft limit.
36fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e  **          of N
36fb0 20 62 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d   bytes on the am
36fc0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
36fd0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
36fe0 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20  allocated.**    
36ff0 20 20 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c        using [sql
37000 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
37010 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
37020 6f 63 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69  oc()] at any poi
37030 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nt.**          i
37040 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  n time..**.** {F
37050 31 36 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c  16352} If a call
37060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
37070 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
37080 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f  e3_realloc()] wo
37090 75 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  uld.**          
370a0 63 61 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20  cause the total 
370b0 61 6d 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61  amount of alloca
370c0 74 65 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78  ted memory to ex
370d0 63 65 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  ceed the.**     
370e0 20 20 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c       soft heap l
370f0 69 6d 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69  imit, then [sqli
37100 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37110 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
37120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
37130 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  an attempt to re
37140 64 75 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  duce the memory 
37150 75 73 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70  usage prior to p
37160 72 6f 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20  roceeding.**    
37170 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d        with the m
37180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37190 20 61 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20   attempt..**.** 
371a0 7b 46 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74  {F16353} Calls t
371b0 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
371c0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
371d0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
371e0 20 74 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20   trigger.**     
371f0 20 20 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f       attempts to
37200 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75   reduce memory u
37210 73 61 67 65 20 74 68 72 6f 75 67 68 20 74 68 65  sage through the
37220 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63  .**          mec
37240 68 61 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20  hanism continue 
37250 65 76 65 6e 20 69 66 20 74 68 65 20 61 74 74 65  even if the atte
37260 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65  mpt to reduce me
37270 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
37280 20 75 73 61 67 65 20 69 73 20 75 6e 73 75 63 63   usage is unsucc
37290 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essful..**.** {F
372a0 31 36 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76  16354} A negativ
372b0 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
372c0 66 6f 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20  for N in a call 
372d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
372e0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
372f0 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e  p_limit(N)] mean
37300 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
37310 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20  no soft.**      
37320 20 20 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61      heap limit a
37330 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  nd [sqlite3_rele
37340 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
37350 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20  ll only be.**   
37360 20 20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68         called wh
37370 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d  en memory is com
37380 70 6c 65 74 65 6c 79 20 65 78 68 61 75 73 74 65  pletely exhauste
37390 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35  d..**.** {F16355
373a0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  } The default va
373b0 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74  lue for the soft
373c0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a   heap limit is z
373d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  ero..**.** {F163
373e0 35 38 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  58} Each call to
373f0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
37400 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76  eap_limit(N)] ov
37410 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20  errides the.**  
37420 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 73          values s
37430 65 74 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20  et by all prior 
37440 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  calls..*/.void s
37450 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
37460 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
37470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
37480 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
37490 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
374a0 66 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35  f A Table {F1285
374b0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
374c0 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73  utine.** returns
374d0 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74   meta-data about
374e0 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
374f0 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
37500 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62   database.** tab
37510 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
37520 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
37530 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64  on handle passed
37540 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
37550 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d  nction .** argum
37560 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ent..**.** The c
37570 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
37580 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
37590 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
375a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
375b0 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  o .** this funct
375c0 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ion. The second 
375d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
375e0 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
375f0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37600 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
37610 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63  emp" or an attac
37620 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
37630 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
37640 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
37650 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69  or NULL. If it i
37660 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
37670 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
37680 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
37690 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
376a0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
376b0 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68   algorithm as th
376c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
376d0 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65  e uses to .** re
376e0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
376f0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
37700 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  es..**.** The th
37710 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
37720 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
37730 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
37740 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
37750 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  umn .** name of 
37760 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
37770 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
37780 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
37790 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a  se parameters .*
377a0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
377b0 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d  *.** Meta inform
377c0 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  ation is returne
377d0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
377e0 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
377f0 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a  ions passed as.*
37800 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75  * the 5th and su
37810 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
37820 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
37830 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65  tion. Any of the
37840 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73  se .** arguments
37850 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e   may be NULL, in
37860 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
37870 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
37880 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a  ement of meta .*
37890 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
378a0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
378b0 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
378c0 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
378d0 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
378e0 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
378f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
37900 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a  ----------.**.**
37910 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
37920 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
37930 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
37940 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
37950 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
37960 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37970 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37980 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
37990 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
379a0 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
379b0 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
379c0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
379d0 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
379e0 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
379f0 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
37a00 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
37a10 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
37a20 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
37a30 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
37a40 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
37a50 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
37a60 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
37a70 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
37a80 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
37a90 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
37aa0 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
37ab0 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
37ac0 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
37ad0 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
37ae0 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
37af0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
37b00 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
37b10 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
37b20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
37b30 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
37b40 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
37b50 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
37b60 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
37b70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
37b80 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
37b90 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
37ba0 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
37bb0 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
37bc0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
37bd0 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
37be0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
37bf0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
37c00 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
37c10 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
37c20 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
37c30 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
37c40 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
37c50 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
37c60 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
37c70 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
37c80 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
37c90 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
37ca0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
37cb0 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
37cc0 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
37cd0 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
37ce0 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
37cf0 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
37d00 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
37d10 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
37d20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
37d30 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
37d40 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
37d50 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
37d60 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
37d70 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
37d80 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
37d90 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
37da0 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
37db0 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
37dc0 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
37dd0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
37de0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
37df0 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
37e00 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
37e10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
37e20 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
37e30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
37e40 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
37e50 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
37e60 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
37e70 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
37e80 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
37e90 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
37ea0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
37eb0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
37ec0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
37ed0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
37ee0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
37ef0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
37f00 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
37f10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37f30 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
37f40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
37f50 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
37f60 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37f70 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
37f80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
37f90 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
37fa0 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
37fb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37fc0 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
37fd0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
37fe0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
37ff0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
38000 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
38010 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
38020 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
38030 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
38040 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
38050 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
38060 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
38070 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
38080 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
38090 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
380a0 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
380b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
380c0 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
380d0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
380e0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
380f0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
38100 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
38110 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
38120 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
38130 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
38140 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
38150 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
38160 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
38170 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  600}.**.** {F126
38180 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
38190 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
381a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74   interface.** at
381b0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
381c0 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
381d0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
381e0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
381f0 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36  .** zFile. {F126
38200 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f  02} The entry po
38210 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46  int is zProc. {F
38220 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
38230 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63   be 0.** in whic
38240 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
38250 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
38260 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74  nt defaults.** t
38270 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
38280 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
38290 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73  * {F12604} The s
382a0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
382b0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
382c0 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72  e shall.** retur
382d0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
382e0 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
382f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
38300 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
38310 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ong..**.** {F126
38320 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  05}.** If an err
38330 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
38340 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
38350 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c   then the.** sql
38360 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
38370 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
38380 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
38390 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
383a0 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
383b0 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
383c0 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ed in memory obt
383d0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
383e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
383f0 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c  * {END}  The cal
38400 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
38410 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
38420 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
38430 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
38440 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
38450 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  606}.** Extensio
38460 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
38470 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
38480 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
38490 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
384a0 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
384b0 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
384c0 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
384d0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
384e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
384f0 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
38500 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
38510 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
38520 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
38530 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
38540 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
38550 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
38560 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
38570 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
38580 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
38590 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
385a0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
385b0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
385c0 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
385d0 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
385e0 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
385f0 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
38600 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
38610 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
38620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
38630 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
38640 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
38650 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a  ing {F12620}.**.
38660 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
38670 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
38680 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
38690 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
386a0 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
386b0 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
386c0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
386d0 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
386e0 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
386f0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
38700 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
38710 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
38720 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
38730 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
38740 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
38750 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
38760 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
38770 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
38780 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20   off.  {F12622} 
38790 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
387a0 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20  ault. {END} See 
387b0 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
387c0 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c  .** {F12621} Cal
387d0 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
387e0 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
387f0 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  ion() routine.**
38800 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
38810 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
38820 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
38830 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
38840 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
38850 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
38860 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  in. {END}.*/.int
38870 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
38880 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
38890 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
388a0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
388b0 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72  API3REF: Make Ar
388c0 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75  rangements To Au
388d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
388e0 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
388f0 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12640}.**.** {F1
38900 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
38910 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ion.** registers
38920 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
38930 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
38940 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
38950 69 6e