/ Hex Artifact Content
Login

Artifact 48a3a643fa711141cb53b1c714be74098770e224:


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 34 20 32 30 30 38 2f  in,v 1.334 2008/
05f0: 30 36 2f 31 38 20 31 33 3a 34 37 3a 30 34 20 64  06/18 13:47: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 66 69 72  rs (N).  The fir
b6a0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
b6b0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
b6c0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
b6d0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
b6e0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
b6f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
b700: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e no more than o
b710: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
b720: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68  r at once per th
b730: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68  read, so.** N sh
b740: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
b750: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
b760: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
b770: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 20 0a  reads.  The sz .
b780: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
b790: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
b7a0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
b7b0: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
b7c0: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
b7d0: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
b7e0: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
b7f0: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
b800: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
b810: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
b820: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
b830: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
b840: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
b850: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
b860: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
b870: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
b880: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
b890: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
b8a0: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
b8b0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
b8c0: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
b8d0: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
b8e0: 64 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ds..** </dd>.**.
b8f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
b900: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
b910: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
b920: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
b930: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
b940: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
b950: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
b960: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
b970: 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 68 65  page cache.  The
b980: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
b990: 75 6d 65 6e 74 73 3a 0a 2a 2a 20 41 20 70 6f 69  uments:.** A poi
b9a0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
b9b0: 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20  ry, the.** size 
b9c0: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
b9d0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
b9e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
b9f0: 73 20 28 4e 29 2e 20 20 54 68 65 20 66 69 72 73  s (N).  The firs
ba00: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
ba10: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
ba20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
ba30: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
ba40: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
ba50: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
ba60: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
ba70: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
ba80: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
ba90: 74 69 73 66 79 0a 2a 2a 20 69 74 73 20 6d 65 6d  tisfy.** its mem
baa0: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
bab0: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
bac0: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
bad0: 63 61 63 68 65 2e 20 20 49 66 20 0a 2a 2a 20 61  cache.  If .** a
bae0: 64 64 69 74 69 6f 6e 61 6c 20 70 61 67 65 20 63  dditional page c
baf0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
bb00: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
bb10: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
bb20: 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c  .** this option,
bb30: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65   then SQLite goe
bb40: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
bb50: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
bb60: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 74  additional.** st
bb70: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
bb80: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bb90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
bba0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AP</dt>.** <dd>T
bbb0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
bbc0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
bbd0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
bbe0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
bbf0: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
bc00: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
bc10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
bc20: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
bc30: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
bc40: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
bc50: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
bc60: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
bc70: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
bc80: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
bc90: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
bca0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
bcb0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
bcc0: 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  * bytes in the m
bcd0: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
bce0: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
bcf0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20  location size.  
bd00: 57 68 65 6e 0a 2a 2a 20 74 68 69 73 20 63 6f 6e  When.** this con
bd10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bd20: 6e 20 69 73 20 75 73 65 64 2c 20 53 51 4c 69 74  n is used, SQLit
bd30: 65 20 6e 65 76 65 72 20 63 61 6c 6c 73 20 74 68  e never calls th
bd40: 65 20 73 79 73 74 65 6d 0a 2a 2a 20 6d 61 6c 6c  e system.** mall
bd50: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
bd60: 69 6f 6e 20 62 75 74 20 69 6e 73 74 65 61 64 20  ion but instead 
bd70: 75 73 65 73 20 74 68 65 20 73 75 70 70 6c 69 65  uses the supplie
bd80: 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  d memory buffer.
bd90: 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 61 6c  ** to satisfy al
bda0: 6c 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  l [sqlite3_mallo
bdb0: 63 28 29 5d 20 72 65 71 75 65 73 74 73 2e 0a 2a  c()] requests..*
bdc0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
bdd0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
bde0: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
bdf0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
be00: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
be10: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
be20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
be30: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
be40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
be50: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
be60: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
be70: 6e 74 20 73 70 65 63 69 66 69 63 73 0a 2a 2a 20  nt specifics.** 
be80: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
be90: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
bea0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
beb0: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
bec0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
bed0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
bee0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
bef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
bf00: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
bf10: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
bf20: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
bf30: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
bf40: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
bf50: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
bf60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
bf70: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
bf80: 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
bf90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
bfa0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
bfb0: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
bfc0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
bfd0: 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
bfe0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69  routines..** Thi
bff0: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
c000: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
c010: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
c020: 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
c030: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
c040: 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
c050: 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
c060: 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
c070: 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
c080: 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
c090: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
c0a0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 20 0a 23 64  .** </dl>.*/ .#d
c0b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c0c0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
c0d0: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
c0e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c0f0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
c100: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
c110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c120: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
c130: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
c140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c150: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
c160: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
c170: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
c180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c190: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
c1a0: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
c1b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c1c0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
c1d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
c1e0: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
c1f0: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
c200: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
c210: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
c220: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
c230: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
c240: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
c250: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
c260: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
c270: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
c280: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
c290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c2a0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
c2b0: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
c2c0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
c2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
c2e0: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
c2f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c300: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
c310: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
c320: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
c330: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
c340: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 0a 2f  _methods* */.../
c350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
c360: 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
c370: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
c380: 20 43 6f 64 65 73 20 7b 46 31 32 32 30 30 7d 0a   Codes {F12200}.
c390: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
c3a0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
c3b0: 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
c3c0: 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
c3d0: 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ables the.** [SQ
c3e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
c3f0: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
c400: 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
c410: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 54   of SQLite..** T
c420: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
c430: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  lt codes are dis
c440: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
c450: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
c460: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
c470: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
c480: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30  TS:.**.** {F1220
c490: 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74  1} Each new [dat
c4a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c4b0: 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65  ] shall have the
c4c0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65   .**          [e
c4d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
c4e0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 0a 2a 2a  odes] feature.**
c4f0: 20 20 20 20 20 20 20 20 20 20 64 69 73 61 62 6c            disabl
c500: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
c510: 2a 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68  *.** {F12202} Th
c520: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
c530: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
c540: 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65  (D,F)] interface
c550: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a   shall enable.**
c560: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
c570: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
c580: 5d 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20  ] for the .**   
c590: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
c5a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69   connection] D i
c5b0: 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65  f the F paramete
c5c0: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  r.**          is
c5d0: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c   true, or disabl
c5e0: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66  e them if F is f
c5f0: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  alse..*/.int sql
c600: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
c610: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
c620: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
c630: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c640: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
c650: 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a  wid {F12220}.**.
c660: 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e  ** Each entry in
c670: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
c680: 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
c690: 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
c6a0: 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
c6b0: 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54  d the "rowid". T
c6c0: 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
c6d0: 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
c6e0: 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
c6f0: 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
c700: 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
c710: 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
c720: 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
c730: 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
c740: 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
c750: 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
c760: 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65   If.** the table
c770: 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
c780: 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52   type INTEGER PR
c790: 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74  IMARY KEY then t
c7a0: 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
c7b0: 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
c7c0: 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
c7d0: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
c7e0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77   returns the row
c7f0: 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  id of the most r
c800: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
c810: 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20  ful INSERT into 
c820: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
c830: 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  m the database c
c840: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f  onnection.** sho
c850: 77 6e 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  wn in the first 
c860: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
c870: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 73 65   successful inse
c880: 72 74 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  rts.** have ever
c890: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 69   occurred on thi
c8a0: 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
c8b0: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
c8c0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
c8d0: 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75  f an INSERT occu
c8e0: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
c8f0: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f  ger, then the ro
c900: 77 69 64 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6e  wid of the.** in
c910: 73 65 72 74 65 64 20 72 6f 77 20 69 73 20 72 65  serted row is re
c920: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
c930: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
c940: 73 20 74 68 65 20 74 72 69 67 67 65 72 0a 2a 2a  s the trigger.**
c950: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 42 75   is running.  Bu
c960: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
c970: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74  er terminates, t
c980: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
c990: 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75  d.** by this rou
c9a0: 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
c9b0: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69  the last value i
c9c0: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74  nserted before t
c9d0: 68 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 66 69  he.** trigger fi
c9e0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e  red..**.** An IN
c9f0: 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73 20  SERT that fails 
ca00: 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
ca10: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
ca20: 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
ca30: 73 66 75 6c 20 69 6e 73 65 72 74 20 61 6e 64 20  sful insert and 
ca40: 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
ca50: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
ca60: 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
ca70: 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53  utine.  Thus INS
ca80: 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
ca90: 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
caa0: 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
cab0: 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
cac0: 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
cad0: 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
cae0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
caf0: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
cb00: 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
cb10: 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68  rtion fails.  Wh
cb20: 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
cb30: 4c 41 43 45 20 0a 2a 2a 20 65 6e 63 6f 75 6e 74  LACE .** encount
cb40: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
cb50: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
cb60: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
cb70: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
cb80: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
cb90: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
cba0: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
cbb0: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
cbc0: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
cbd0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
cbe0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
cbf0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
cc00: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
cc10: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 20 0a 2a  is interface. .*
cc20: 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72  *.** For the pur
cc30: 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
cc40: 75 74 69 6e 65 2c 20 61 6e 20 69 6e 73 65 72 74  utine, an insert
cc50: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
cc60: 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
cc70: 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
cc80: 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
cc90: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
cca0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
ccb0: 2a 2a 20 7b 46 31 32 32 32 31 7d 20 54 68 65 20  ** {F12221} The 
ccc0: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
ccd0: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75  sert_rowid()] fu
cce0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
ccf0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
cd00: 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74  owid of the most
cd10: 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
cd20: 75 6c 20 69 6e 73 65 72 74 20 64 6f 6e 65 0a 2a  ul insert done.*
cd30: 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
cd40: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
cd50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 77  connection and w
cd60: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
cd70: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 68 69  *          or hi
cd80: 67 68 65 72 20 6c 65 76 65 6c 20 74 72 69 67 67  gher level trigg
cd90: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a  er context, or z
cda0: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76  ero if there hav
cdb0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
cdc0: 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67  en no qualifying
cdd0: 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20   inserts..**.** 
cde0: 7b 46 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71  {F12223} The [sq
cdf0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
ce00: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
ce10: 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ion returns.**  
ce20: 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c          same val
ce30: 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  ue when called f
ce40: 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69  rom the same tri
ce50: 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20  gger context.** 
ce60: 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61           immedia
ce70: 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20  tely before and 
ce80: 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b  after a ROLLBACK
ce90: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
cea0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
ceb0: 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  32} If a separat
cec0: 65 20 74 68 72 65 61 64 20 64 6f 65 73 20 61 20  e thread does a 
ced0: 6e 65 77 20 69 6e 73 65 72 74 20 6f 6e 20 74 68  new insert on th
cee0: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
cef0: 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e     database conn
cf00: 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
cf10: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
cf20: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
cf30: 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
cf40: 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
cf50: 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
cf60: 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
cf70: 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20  rowid,.**       
cf80: 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75     then the valu
cf90: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
cfa0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
cfb0: 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
cfc0: 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65  *          unpre
cfd0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
cfe0: 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
cff0: 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
d000: 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20  he new.**       
d010: 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72     last insert r
d020: 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  owid..*/.sqlite3
d030: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
d040: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
d050: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
d060: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
d070: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
d080: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
d090: 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12240}.**.** Th
d0a0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
d0b0: 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
d0c0: 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
d0d0: 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
d0e0: 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
d0f0: 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
d100: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
d110: 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
d120: 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
d130: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  he connection sp
d140: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
d150: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
d160: 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67 65 73   Only.** changes
d170: 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
d180: 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
d190: 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
d1a0: 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45 54 45  TE, or.** DELETE
d1b0: 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
d1c0: 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
d1d0: 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
d1e0: 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
d1f0: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
d200: 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
d210: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
d220: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
d230: 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
d240: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
d250: 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
d260: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
d270: 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
d280: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
d290: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
d2a0: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
d2b0: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
d2c0: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
d2d0: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
d2e0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
d2f0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
d300: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
d310: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
d320: 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
d330: 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
d340: 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
d350: 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
d360: 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
d370: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
d380: 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
d390: 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
d3a0: 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
d3b0: 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
d3c0: 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
d3d0: 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
d3e0: 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
d3f0: 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
d400: 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
d410: 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
d420: 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
d430: 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
d440: 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
d450: 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
d460: 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
d470: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
d480: 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
d490: 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
d4a0: 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
d4b0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
d4c0: 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
d4d0: 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
d4e0: 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
d4f0: 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
d500: 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
d510: 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
d520: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
d530: 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
d540: 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
d550: 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
d560: 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
d570: 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
d580: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
d590: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
d5a0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
d5b0: 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
d5c0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
d5d0: 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
d5e0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
d5f0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
d600: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
d610: 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
d620: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
d630: 20 53 6f 20 77 68 65 6e 20 63 61 6c 6c 65 64 20   So when called 
d640: 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
d650: 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
d660: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
d670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
d680: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
d690: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
d6a0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
d6b0: 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
d6c0: 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
d6d0: 20 6c 65 76 65 6c 2e 0a 2a 2a 20 57 69 74 68 69   level..** Withi
d6e0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
d6f0: 74 72 69 67 67 65 72 2c 20 74 68 65 20 73 71 6c  trigger, the sql
d700: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
d710: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 6e 20  nterface.** can 
d720: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
d730: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
d740: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
d750: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
d760: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
d770: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
d780: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
d790: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
d7a0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
d7b0: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
d7c0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
d7d0: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
d7e0: 6e 63 6c 75 64 65 20 69 6e 20 63 68 61 6e 67 65  nclude in change
d7f0: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
d800: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
d810: 20 74 68 65 79 20 68 61 76 65 20 74 68 65 69 72   they have their
d820: 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a   own context..**
d830: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
d840: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
d850: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
d860: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 0a 2a 2a  able" without.**
d870: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 20   a WHERE clause 
d880: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
d890: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
d8a0: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
d8b0: 6d 75 63 68 0a 2a 2a 20 66 61 73 74 65 72 20 74  much.** faster t
d8c0: 68 61 6e 20 67 6f 69 6e 67 20 74 68 72 6f 75 67  han going throug
d8d0: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
d8e0: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
d8f0: 74 73 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  ts from the.** t
d900: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
d910: 6f 66 20 74 68 69 73 20 6f 70 74 69 6d 69 7a 61  of this optimiza
d920: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
d930: 6f 6e 73 20 69 6e 0a 2a 2a 20 22 44 45 4c 45 54  ons in.** "DELET
d940: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
d950: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
d960: 73 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  s and will not b
d970: 65 20 63 6f 75 6e 74 65 64 0a 2a 2a 20 62 79 20  e counted.** by 
d980: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
d990: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
d9a0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d9b0: 29 5d 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  )] functions..**
d9c0: 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
d9d0: 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
d9e0: 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
d9f0: 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
da00: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
da10: 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
da20: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ead..**.** INVAR
da30: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
da40: 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2241} The [sqlit
da50: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  e3_changes()] fu
da60: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
da70: 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
da80: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  f.**          ro
da90: 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
daa0: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
dab0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
dac0: 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  TE,.**          
dad0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
dae0: 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ent on the same 
daf0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
db00: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
db10: 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73      within the s
db20: 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72  ame or higher tr
db30: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
db40: 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
db50: 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
db60: 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75   not been any qu
db70: 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61  alifying row cha
db80: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  nges..**.** {F12
db90: 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20  243} Statements 
dba0: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c  of the form "DEL
dbb0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61  ETE FROM tablena
dbc0: 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20  me" with no.**  
dbd0: 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c          WHERE cl
dbe0: 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65  ause shall cause
dbf0: 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
dc00: 73 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  s to .**        
dc10: 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67    [sqlite3_chang
dc20: 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  es()] to return 
dc30: 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73  zero, regardless
dc40: 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
dc50: 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f      number of ro
dc60: 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  ws originally in
dc70: 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   the table..**.*
dc80: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
dc90: 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49 66  *.** {U12252} If
dca0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
dcb0: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
dcc0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
dcd0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
dce0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
dcf0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
dd00: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
dd10: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
dd20: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
dd30: 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69        is unpredi
dd40: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
dd50: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
dd60: 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
dd70: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
dd80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
dd90: 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
dda0: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32  ws Modified {F12
ddb0: 32 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  260}.***.** This
ddc0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
ddd0: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
dde0: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
ddf0: 65 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54 2c  ed.** by INSERT,
de00: 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
de10: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  E statements sin
de20: 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
de30: 68 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70  handle.** was op
de40: 65 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e 74  ened.  The count
de50: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
de60: 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74  anges from all t
de70: 72 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65 78  rigger.** contex
de80: 74 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f 75  ts.  But the cou
de90: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
dea0: 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
deb0: 20 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74   to.** implement
dec0: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
ded0: 69 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61 63  ints, do rollbac
dee0: 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
def0: 65 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52  essing,.** or DR
df00: 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73  OP table process
df10: 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e  ing..** The chan
df20: 67 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  ges.** are count
df30: 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
df40: 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
df50: 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
df60: 6f 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68  ompleted .** (wh
df70: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
df80: 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65   handle is passe
df90: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
dfa0: 73 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73  set()] or .** [s
dfb0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
dfc0: 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  )])..**.** SQLit
dfd0: 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
dfe0: 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
dff0: 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
e000: 68 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20  hout.** a WHERE 
e010: 63 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69  clause by droppi
e020: 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
e030: 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
e040: 68 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66  his is much.** f
e050: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
e060: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
e070: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
e080: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
e090: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
e0a0: 65 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69  ecause of.** thi
e0b0: 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  s optimization, 
e0c0: 74 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74  the change count
e0d0: 20 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f   for "DELETE FRO
e0e0: 4d 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65  M table" will be
e0f0: 0a 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c  .** zero regardl
e100: 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
e110: 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
e120: 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
e130: 6c 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62  ly in the.** tab
e140: 6c 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63  le. To get an ac
e150: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
e160: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
e170: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
e180: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
e190: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
e1a0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  nstead..**.** Se
e1b0: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
e1c0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
e1d0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
e1e0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a  INVARIANTS:.** .
e1f0: 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20  ** {F12261} The 
e200: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
e210: 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e  hanges()] return
e220: 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
e230: 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
e240: 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
e250: 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20  used by INSERT, 
e260: 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44  UPDATE, and/or D
e270: 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20  ELETE.**        
e280: 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20    statements on 
e290: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
e2a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
e2b0: 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20  in any.**       
e2c0: 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
e2d0: 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61  xt, since the da
e2e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e2f0: 6e 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  n was.**        
e300: 20 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a    created..**.**
e310: 20 7b 46 31 32 32 36 33 7d 20 53 74 61 74 65 6d   {F12263} Statem
e320: 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ents of the form
e330: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
e340: 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f  blename" with no
e350: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45  .**          WHE
e360: 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20  RE clause shall 
e370: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
e380: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
e390: 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [sq
e3a0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
e3b0: 67 65 73 28 29 5d 0a 2a 2a 0a 2a 2a 20 4c 49 4d  ges()].**.** LIM
e3c0: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
e3d0: 7b 55 31 32 32 36 34 7d 20 49 66 20 61 20 73 65  {U12264} If a se
e3e0: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
e3f0: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
e400: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
e410: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
e420: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
e430: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
e440: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
e450: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
e460: 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  e .**          r
e470: 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
e480: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
e490: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
e4a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
e4b0: 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
e4c0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
e4d0: 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
e4e0: 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
e4f0: 75 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a  uery {F12270}.**
e500: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
e510: 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
e520: 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
e530: 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
e540: 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
e550: 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
e560: 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
e570: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
e580: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
e590: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
e5a0: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
e5b0: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
e5c0: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
e5d0: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
e5e0: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
e5f0: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
e600: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
e610: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  iately..**.** It
e620: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
e630: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
e640: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
e650: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
e660: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
e670: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
e680: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
e690: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
e6a0: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
e6b0: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
e6c0: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61  outine with a da
e6d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e6e0: 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  n that.** is clo
e6f0: 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
e700: 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
e710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
e720: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
e730: 61 6e 20 53 51 4c 20 69 73 20 76 65 72 79 20 6e  an SQL is very n
e740: 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
e750: 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 20  t the time when 
e760: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
e770: 74 28 29 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64  t().** is called
e780: 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
e790: 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
e7a0: 72 74 75 6e 69 74 79 20 74 6f 20 62 65 20 69 6e  rtunity to be in
e7b0: 74 65 72 72 75 70 74 65 64 2e 0a 2a 2a 20 49 74  terrupted..** It
e7c0: 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
e7d0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
e7e0: 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
e7f0: 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
e800: 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
e810: 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  rn.** [SQLITE_IN
e820: 54 45 52 52 55 50 54 5d 2e 20 20 49 66 20 74 68  TERRUPT].  If th
e830: 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
e840: 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
e850: 6e 0a 2a 2a 20 49 4e 53 45 52 54 2c 20 55 50 44  n.** INSERT, UPD
e860: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 74  ATE, or DELETE t
e870: 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
e880: 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
e890: 63 74 69 6f 6e 2c 20 0a 2a 2a 20 74 68 65 6e 20  ction, .** then 
e8a0: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
e8b0: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72  action will be r
e8c0: 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
e8d0: 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 20 41 20 63  atically..** A c
e8e0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
e8f0: 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e  nterrupt() has n
e900: 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
e910: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
e920: 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
e930: 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74  fter sqlite3_int
e940: 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
e950: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
e960: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37  TS:.**.** {F1227
e970: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
e980: 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74  interrupt()] int
e990: 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63  erface will forc
e9a0: 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a  e all running.**
e9b0: 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
e9c0: 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
e9d0: 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ted with the sam
e9e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
e9f0: 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
ea00: 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20    to halt after 
ea10: 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f  processing at mo
ea20: 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61  st one additiona
ea30: 6c 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20  l row of.**     
ea40: 20 20 20 20 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a       data..**.**
ea50: 20 7b 46 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {F12272} Any SQ
ea60: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
ea70: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
ea80: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
ea90: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
eaa0: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
eab0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
eac0: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  PT]..**.** LIMIT
ead0: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55  ATIONS:.**.** {U
eae0: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
eaf0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eb00: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
eb10: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
eb20: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
eb30: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
eb40: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
eb50: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
eb60: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
eb70: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
eb80: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
eb90: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
eba0: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
ebb0: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
ebc0: 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10510}.**.** T
ebd0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
ebe0: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
ebf0: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
ec00: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
ec10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
ec20: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
ec30: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
ec40: 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
ec50: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
ec60: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
ec70: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
ec80: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
ec90: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
eca0: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
ecb0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
ecc0: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
ecd0: 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
ece0: 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
ecf0: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
ed00: 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
ed10: 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
ed20: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
ed30: 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
ed40: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
ed50: 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
ed60: 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
ed70: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
ed80: 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
ed90: 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
eda0: 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
edb0: 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
edc0: 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
edd0: 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
ede0: 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
edf0: 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
ee00: 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
ee10: 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
ee20: 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
ee30: 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
ee40: 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
ee50: 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
ee60: 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
ee70: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
ee80: 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
ee90: 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 61 6e  parse the SQL an
eea0: 64 0a 2a 2a 20 73 6f 20 77 69 6c 6c 20 6e 6f 74  d.** so will not
eeb0: 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
eec0: 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
eed0: 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  SQL..**.** INVAR
eee0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
eef0: 30 35 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65  0511} The sqlite
ef00: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e 64  3_complete() and
ef10: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
ef20: 65 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  e16() functions.
ef30: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
ef40: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
ef50: 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  o) if and only i
ef60: 66 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 20 20  f the last.**   
ef70: 20 20 20 20 20 20 20 6e 6f 6e 2d 77 68 69 74 65         non-white
ef80: 73 70 61 63 65 20 74 6f 6b 65 6e 20 69 6e 20 74  space token in t
ef90: 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20  heir input is a 
efa0: 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 0a 2a  semicolon that.*
efb0: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
efc0: 74 20 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65  t in between the
efd0: 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f   BEGIN and END o
efe0: 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47  f a CREATE TRIGG
eff0: 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ER.**          s
f000: 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
f010: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
f020: 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54 68 65 20  ** {U10512} The 
f030: 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33  input to sqlite3
f040: 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73 74  _complete() must
f050: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
f060: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
f070: 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
f080: 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20 54  **.** {U10513} T
f090: 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69  he input to sqli
f0a0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
f0b0: 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
f0c0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
f0d0: 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73 74         UTF-16 st
f0e0: 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
f0f0: 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
f100: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
f110: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
f120: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
f130: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
f140: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
f150: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
f160: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
f170: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
f180: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
f190: 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12310}.**.** T
f1a0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 64 65 6e  his routine iden
f1b0: 74 69 66 69 65 73 20 61 20 63 61 6c 6c 62 61 63  tifies a callbac
f1c0: 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
f1d0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 69 6e 76 6f  might be.** invo
f1e0: 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
f1f0: 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
f200: 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
f210: 73 65 20 74 61 62 6c 65 20 0a 2a 2a 20 74 68 61  se table .** tha
f220: 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
f230: 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
f240: 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 49 66 20 74 68  locked..** If th
f250: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
f260: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
f270: 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
f280: 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
f290: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
f2a0: 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
f2b0: 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
f2c0: 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 0a  ering the lock..
f2d0: 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63  ** If the busy c
f2e0: 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 4e  allback is not N
f2f0: 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ULL, then the.**
f300: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
f310: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
f320: 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  wo arguments.  T
f330: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
f340: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
f350: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
f360: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
f370: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
f380: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
f390: 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  t to this routin
f3a0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  e.  The second a
f3b0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
f3c0: 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68 65  e handler is the
f3d0: 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
f3e0: 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
f3f0: 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
f400: 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
f410: 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
f420: 74 2e 20 20 20 49 66 20 74 68 65 0a 2a 2a 20 62  t.   If the.** b
f430: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
f440: 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
f450: 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
f460: 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
f470: 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
f480: 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
f490: 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
f4a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
f4b0: 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  D] is returned..
f4c0: 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
f4d0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
f4e0: 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
f4f0: 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
f500: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
f510: 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
f520: 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
f530: 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
f540: 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
f550: 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
f560: 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
f570: 6e 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20  ntee that.** it 
f580: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
f590: 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
f5a0: 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a  ck contention..*
f5b0: 2a 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  * If SQLite dete
f5c0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
f5d0: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
f5e0: 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
f5f0: 6c 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c  lt in.** a deadl
f600: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
f610: 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
f620: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
f630: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
f640: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
f650: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
f660: 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
f670: 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
f680: 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
f690: 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
f6a0: 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
f6b0: 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
f6c0: 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
f6d0: 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
f6e0: 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
f6f0: 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
f700: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
f710: 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
f720: 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
f730: 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
f740: 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
f750: 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
f760: 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
f770: 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
f780: 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
f790: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
f7a0: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
f7b0: 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
f7c0: 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
f7d0: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
f7e0: 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
f7f0: 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
f800: 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
f810: 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
f820: 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
f830: 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
f840: 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
f850: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
f860: 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
f870: 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
f880: 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
f890: 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
f8a0: 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
f8b0: 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
f8c0: 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
f8d0: 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
f8e0: 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
f8f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
f900: 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
f910: 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
f920: 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
f930: 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
f940: 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
f950: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
f960: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
f970: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
f980: 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
f990: 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
f9a0: 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
f9b0: 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
f9c0: 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
f9d0: 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
f9e0: 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
f9f0: 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
fa00: 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
fa10: 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
fa20: 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
fa30: 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
fa40: 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
fa50: 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
fa60: 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
fa70: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
fa80: 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
fa90: 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
faa0: 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66  .** readers.  If
fab0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
fac0: 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
fad0: 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
fae0: 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
faf0: 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
fb00: 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
fb10: 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
fb20: 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
fb30: 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
fb40: 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
fb50: 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
fb60: 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
fb70: 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
fb80: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
fb90: 20 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64    This error cod
fba0: 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66  e promotion.** f
fbb0: 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74  orces an automat
fbc0: 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74  ic rollback of t
fbd0: 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65  he changes.  See
fbe0: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d   the.** <a href=
fbf0: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69  "http://www.sqli
fc00: 74 65 2e 6f 72 67 2f 63 76 73 74 72 61 63 2f 77  te.org/cvstrac/w
fc10: 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
fc20: 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
fc30: 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
fc40: 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
fc50: 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
fc60: 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
fc70: 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
fc80: 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
fc90: 0a 2a 2a 09 0a 2a 2a 20 54 68 65 72 65 20 63 61  .**..** There ca
fca0: 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
fcb0: 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
fcc0: 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
fcd0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
fce0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 74 74 69 6e  nection.  Settin
fcf0: 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
fd00: 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 20  dler clears any 
fd10: 70 72 65 76 69 6f 75 73 20 6f 6e 65 2e 20 0a 2a  previous one. .*
fd20: 2a 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c  * Note that call
fd30: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
fd40: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 77 69 6c  y_timeout()] wil
fd50: 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
fd60: 65 61 72 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ear.** the busy 
fd70: 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  handler..**.** I
fd80: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
fd90: 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20 5b 73   {F12311} The [s
fda0: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
fdb0: 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ler()] function 
fdc0: 72 65 70 6c 61 63 65 73 20 74 68 65 20 62 75 73  replaces the bus
fdd0: 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20 20  y handler.**    
fde0: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
fdf0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
fe00: 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69  onnection identi
fe10: 66 69 65 64 20 62 79 20 74 68 65 20 31 73 74 0a  fied by the 1st.
fe20: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
fe30: 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e 65 77  meter with a new
fe40: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 64   busy handler id
fe50: 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
fe60: 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20 20  2nd and 3rd.**  
fe70: 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
fe80: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  rs..**.** {F1231
fe90: 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  2} The default b
fea0: 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
feb0: 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
fec0: 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c 4c  nections is NULL
fed0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34 7d  ..**.** {F12314}
fee0: 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72   When two or mor
fef0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
ff00: 63 74 69 6f 6e 20 73 68 61 72 65 20 61 20 5b 73  ction share a [s
ff10: 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
ff20: 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d  ared_cache | com
ff30: 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20  mon cache],.**  
ff40: 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79          the busy
ff50: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
ff60: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
ff70: 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75  tion currently u
ff80: 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
ff90: 20 74 68 65 20 63 61 63 68 65 20 69 73 20 69 6e   the cache is in
ffa0: 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63  voked when the c
ffb0: 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  ache encounters 
ffc0: 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  a lock..**.** {F
ffd0: 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79  12316} If a busy
ffe0: 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
fff0: 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  k returns zero, 
10000 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 0a  then the SQLite.
10010 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
10020 72 66 61 63 65 20 74 68 61 74 20 70 72 6f 76 6f  rface that provo
10030 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20  ked the locking 
10040 65 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72  event will retur
10050 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
10060 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
10070 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51 4c 69  ** {F12318} SQLi
10080 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73 20  te will invokes 
10090 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
100a0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
100b0 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20  nts which.**    
100c0 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79        are a copy
100d0 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20   of the pointer 
100e0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
100f0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
10100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10110 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10120 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e  er()] and a coun
10130 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
10140 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20  of prior.**     
10150 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73       invocations
10160 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e   of the busy han
10170 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d  dler for the sam
10180 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
10190 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
101a0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31  NS:.**.** {U1231
101b0 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  9} A busy handle
101c0 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  r should not cal
101d0 6c 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  l close the data
101e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
101f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 70  **          or p
10200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10210 74 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  t that invoked t
10220 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
10230 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10240 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
10250 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
10260 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
10270 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10280 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
10290 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a  meout {F12340}.*
102a0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
102b0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
102c0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
102d0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 0a 2a   busy handler].*
102e0 2a 20 74 68 61 74 20 73 6c 65 65 70 73 20 66 6f  * that sleeps fo
102f0 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e 20 61  r a while when a
10300 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  .** table is loc
10310 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
10320 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  r will sleep mul
10330 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
10340 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74 20 22  l .** at least "
10350 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
10360 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68 61 76   of sleeping hav
10370 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 7b 46 31  e been done. {F1
10380 32 33 34 33 7d 20 41 66 74 65 72 0a 2a 2a 20 22  2343} After.** "
10390 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
103a0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 20 74 68   of sleeping, th
103b0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
103c0 73 20 30 20 77 68 69 63 68 0a 2a 2a 20 63 61 75  s 0 which.** cau
103d0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
103e0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 5b  p()] to return [
103f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
10400 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10410 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
10420 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
10430 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
10440 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
10450 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
10460 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
10470 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
10480 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
10490 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
104a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
104b0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
104c0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
104d0 74 69 6f 6e 2e 20 20 49 66 20 61 6e 6f 74 68 65  tion.  If anothe
104e0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  r busy handler w
104f0 61 73 20 64 65 66 69 6e 65 64 20 20 0a 2a 2a 20  as defined  .** 
10500 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
10510 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
10520 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
10530 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
10540 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
10550 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
10560 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eared..**.** INV
10570 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10580 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F12341} The [sql
10590 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
105a0 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f 76  t()] function ov
105b0 65 72 72 69 64 65 73 20 61 6e 79 20 70 72 69 6f  errides any prio
105c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
105d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
105e0 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  out()] or [sqlit
105f0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10600 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  )] setting.**   
10610 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
10620 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
10630 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ection..**.** {F
10640 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e  12343} If the 2n
10650 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
10660 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
10670 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20  eout()] is less 
10680 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
10690 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
106a0 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73 79  o, then the busy
106b0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
106c0 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20  red so that.**  
106d0 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62 73          all subs
106e0 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65  equent locking e
106f0 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65 6c  vents immediatel
10700 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  y return [SQLITE
10710 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _BUSY]..**.** {F
10720 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32 6e  12344} If the 2n
10730 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
10740 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
10750 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f 73  eout()] is a pos
10760 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  itive.**        
10770 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e    number N, then
10780 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
10790 69 73 20 73 65 74 20 74 68 61 74 20 72 65 70 65  is set that repe
107a0 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
107b0 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
107c0 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
107d0 74 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63  the VFS interfac
107e0 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  e until either t
107f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  he.**          l
10800 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
10810 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
10820 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20 72 65  ve sleep time re
10830 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20 20  ported back.**  
10840 20 20 20 20 20 20 20 20 62 79 20 78 53 6c 65 65          by xSlee
10850 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
10860 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
10870 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
10880 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
10890 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
108a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
108b0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
108c0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
108d0 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a 2a  ries {F12370}.**
108e0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
108f0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
10900 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
10910 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
10920 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
10930 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
10940 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
10950 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
10960 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
10970 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
10980 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
10990 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
109a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
109b0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
109c0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
109d0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
109e0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
109f0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
10a00 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
10a10 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
10a20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
10a30 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
10a40 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
10a50 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
10a60 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
10a70 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
10a80 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
10a90 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10aa0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
10ab0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
10ac0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
10ad0 46 2d 38 20 73 74 72 69 6e 67 73 2e 20 20 54 68  F-8 strings.  Th
10ae0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
10af0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
10b00 61 72 72 61 79 2e 20 20 0a 2a 2a 20 54 68 65 20  array.  .** The 
10b10 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
10b20 20 70 6f 69 6e 74 20 74 6f 20 7a 65 72 6f 2d 74   point to zero-t
10b30 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
10b40 73 20 74 68 61 74 20 0a 2a 2a 20 63 6f 6e 74 61  s that .** conta
10b50 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
10b60 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
10b70 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
10b80 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
10b90 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
10ba0 2e 20 20 4e 55 4c 4c 0a 2a 2a 20 76 61 6c 75 65  .  NULL.** value
10bb0 73 20 61 72 65 20 67 69 76 65 20 61 20 4e 55 4c  s are give a NUL
10bc0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 41 6c 6c 20  L pointer.  All 
10bd0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
10be0 20 69 6e 0a 2a 2a 20 74 68 65 69 72 20 55 54 46   in.** their UTF
10bf0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
10c00 65 64 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ed string repres
10c10 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
10c20 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
10c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
10c40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
10c50 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
10c60 6f 6e 73 69 73 74 73 20 6f 66 20 6f 6e 65 20 6f  onsists of one o
10c70 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
10c80 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
10c90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
10ca0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
10cb0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
10cc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10cd0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
10ce0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
10cf0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
10d00 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
10d10 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
10d20 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
10d30 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
10d40 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
10d50 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
10d60 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
10d70 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
10d80 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
10d90 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
10da0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
10db0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
10dc0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
10dd0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
10de0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
10df0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
10e00 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
10e10 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
10e20 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
10e30 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
10e40 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
10e50 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
10e60 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
10e70 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
10e80 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
10e90 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
10ea0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
10eb0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
10ec0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
10ed0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
10ee0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
10ef0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
10f00 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
10f10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
10f20 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
10f30 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
10f40 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
10f50 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
10f60 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
10f70 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
10f80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
10f90 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
10fa0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
10fb0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
10fc0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
10fd0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
10fe0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
10ff0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
11000 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
11010 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
11020 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
11030 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11040 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11050 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
11060 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
11070 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
11080 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
11090 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
110a0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
110b0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
110c0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
110d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
110e0 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
110f0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
11100 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
11110 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
11120 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
11130 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
11140 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
11150 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
11160 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
11170 6c 64 20 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  ld .** pass the 
11180 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
11190 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
111a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
111b0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  e() in order to 
111c0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
111d0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
111e0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
111f0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
11200 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  e .** [sqlite3_m
11210 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
11220 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
11230 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
11240 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
11250 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
11260 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
11270 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
11280 74 6c 79 2e 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b  tly.  Only .** [
11290 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
112a0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
112b0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
112c0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
112d0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
112e0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
112f0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
11300 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
11310 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
11320 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
11330 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
11340 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
11350 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
11360 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
11370 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
11380 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
11390 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
113a0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
113b0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
113c0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
113d0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
113e0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
113f0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
11400 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
11410 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
11420 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
11430 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
11440 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
11450 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
11460 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
11470 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
11480 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
11490 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  g()]..**.** INVA
114a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
114b0 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c  12371} If a [sql
114c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
114d0 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79  ] fails a memory
114e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
114f0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
11500 20 66 72 65 65 73 20 74 68 65 20 72 65 73 75 6c   frees the resul
11510 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
11520 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
11530 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
11540 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63     query in proc
11550 65 73 73 2c 20 73 6b 69 70 73 20 61 6e 79 20 73  ess, skips any s
11560 75 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65  ubsequent querie
11570 73 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 20  s, sets the.**  
11580 20 20 20 20 20 20 20 20 2a 72 65 73 75 6c 74 70          *resultp
11590 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20   output pointer 
115a0 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75  to NULL and retu
115b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  rns [SQLITE_NOME
115c0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  M]..**.** {F1237
115d0 33 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c 75 6d  3} If the ncolum
115e0 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  n parameter to [
115f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11600 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
11610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
11620 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  n [sqlite3_get_t
11630 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68  able()] write th
11640 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
11650 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  mns in the.**   
11660 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
11670 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
11680 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20  nto *ncolumn if 
11690 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20  the query is.** 
116a0 20 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73           success
116b0 66 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63  ful (if the func
116c0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c  tion returns SQL
116d0 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK)..**.** {
116e0 46 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 6e  F12374} If the n
116f0 72 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f  row parameter to
11700 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
11710 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55  ble()] is not NU
11720 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
11730 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  hen [sqlite3_get
11740 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 20  _table()] write 
11750 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11760 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ws in the.**    
11770 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
11780 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
11790 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74 68 65 20  to *nrow if the 
117a0 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20  query is.**     
117b0 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20       successful 
117c0 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  (if the function
117d0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
117e0 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  OK)..**.** {F123
117f0 37 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  76} The [sqlite3
11800 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 75  _get_table()] fu
11810 6e 63 74 69 6f 6e 20 73 65 74 73 20 69 74 73 20  nction sets its 
11820 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a  *ncolumn value.*
11830 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
11840 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
11850 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
11860 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
11870 72 79 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ry in the.**    
11880 20 20 20 20 20 20 73 71 6c 20 70 61 72 61 6d 65        sql parame
11890 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65 72 6f 20  ter, or to zero 
118a0 69 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 20  if the query in 
118b0 73 71 6c 20 68 61 73 20 61 6e 20 65 6d 70 74 79  sql has an empty
118c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
118d0 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
118e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
118f0 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  e(.  sqlite3*,  
11900 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
11910 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
11920 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
11930 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c  sql,      /* SQL
11940 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
11950 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52   */.  char ***pR
11960 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52  esult,      /* R
11970 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
11980 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72  ery */.  int *nr
11990 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  ow,            /
119a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
119b0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
119c0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  here */.  int *n
119d0 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20  column,         
119e0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
119f0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
11a00 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
11a10 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
11a20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
11a30 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
11a40 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
11a50 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
11a60 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
11a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
11a80 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
11a90 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
11aa0 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17400}.**.** 
11ab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11ac0 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
11ad0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
11ae0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
11af0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
11b00 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11b10 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
11b20 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
11b30 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
11b40 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
11b50 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
11b60 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
11b70 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
11b80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11b90 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
11ba0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
11bb0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
11bc0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
11bd0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
11be0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20  ite3_free()].   
11bf0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
11c00 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
11c10 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
11c20 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
11c30 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
11c40 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
11c50 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
11c60 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
11c70 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
11c80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
11c90 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
11ca0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
11cb0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
11cc0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11cd0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
11ce0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
11cf0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
11d00 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
11d10 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
11d20 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
11d30 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
11d40 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
11d50 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
11d60 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
11d70 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
11d80 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
11d90 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
11da0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
11db0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
11dc0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
11dd0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
11de0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
11df0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
11e00 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
11e10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
11e20 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
11e30 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
11e40 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
11e50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
11e60 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
11e70 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
11e80 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
11e90 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
11ea0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
11eb0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
11ec0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
11ed0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
11ee0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
11ef0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
11f00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
11f10 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
11f20 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
11f30 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
11f40 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
11f50 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
11f60 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
11f70 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
11f80 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
11f90 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
11fa0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
11fb0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
11fc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
11fd0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
11fe0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
11ff0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
12000 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
12010 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
12020 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
12030 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
12040 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
12050 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
12060 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
12070 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
12080 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
12090 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
120a0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
120b0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
120c0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
120d0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
120e0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
120f0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
12100 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
12110 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
12120 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
12130 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
12140 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
12150 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
12160 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
12170 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
12180 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
12190 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
121a0 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
121b0 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
121c0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
121d0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
121e0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
121f0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
12200 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
12210 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
12220 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
12230 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
12240 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
12250 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
12260 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
12270 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
12280 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
12290 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
122a0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
122b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
122c0 70 6c 65 2c 20 73 6f 20 73 6f 6d 65 20 73 74 72  ple, so some str
122d0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 63 6f 6e  ing variable con
122e0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
122f0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
12300 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
12310 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
12320 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
12330 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
12340 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
12350 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
12360 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
12370 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
12380 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
12390 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
123a0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
123b0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
123c0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
123d0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
123e0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
123f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
12400 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
12410 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
12420 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
12430 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
12440 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
12450 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
12460 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
12470 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
12480 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
12490 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
124a0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
124b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
124c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
124d0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
124e0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
124f0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
12500 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
12510 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
12520 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
12530 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
12540 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
12550 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
12560 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
12570 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
12580 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
12590 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
125a0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
125b0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
125c0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
125d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
125e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
125f0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
12600 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
12610 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
12620 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
12630 75 0a 2a 2a 20 73 68 6f 75 6c 64 20 61 6c 77 61  u.** should alwa
12640 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
12650 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
12660 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
12670 20 61 20 73 74 72 69 6e 67 20 0a 2a 2a 20 6c 69   a string .** li
12680 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  teral..**.** The
12690 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
126a0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
126b0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
126c0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
126d0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
126e0 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
126f0 72 69 6e 67 2e 20 20 4f 72 20 69 66 20 74 68 65  ring.  Or if the
12700 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
12710 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6c 69  e argument.** li
12720 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
12730 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
12740 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
12750 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 20 73 69  ULL" (without si
12760 6e 67 6c 65 0a 2a 2a 20 71 75 6f 74 65 73 29 20  ngle.** quotes) 
12770 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
12780 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d  %Q option. {END}
12790 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
127a0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
127b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
127c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
127d0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
127e0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
127f0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
12800 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
12810 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
12820 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
12830 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
12840 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
12850 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12860 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
12870 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
12880 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
12890 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
128a0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
128b0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
128c0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
128d0 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
128e0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
128f0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
12900 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
12910 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
12920 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
12930 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
12940 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
12950 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
12960 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
12970 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
12980 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
12990 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
129a0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
129b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
129c0 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54  *.** {F17403}  T
129d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  he [sqlite3_mpri
129e0 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ntf()] and [sqli
129f0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20  te3_vmprintf()] 
12a00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20  interfaces.**   
12a10 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65          return e
12a20 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74  ither pointers t
12a30 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
12a40 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
12a50 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20  held in.**      
12a60 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61       memory obta
12a70 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
12a80 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
12a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66  NULL pointers if
12aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
12ab0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
12ac0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73  _malloc()] fails
12ad0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d  ..**.** {F17406}
12ae0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
12af0 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
12b00 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65  face writes a ze
12b10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
12b20 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38             UTF-8
12b30 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65   string into the
12b40 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20   buffer pointed 
12b50 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
12b60 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
12b70 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64          provided
12b80 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20   that the first 
12b90 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65  parameter is gre
12ba0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a  ater than zero..
12bb0 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20  **.** {F17407}  
12bc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
12bd0 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
12be0 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74  ce does not writ
12bf0 65 73 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20  es slots of.**  
12c00 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74           its out
12c10 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20  put buffer (the 
12c20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12c30 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61  ) outside the ra
12c40 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
12c50 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d   of 0 through N-
12c60 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68  1 (where N is th
12c70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12c80 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r).**           
12c90 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
12ca0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
12cb0 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
12cc0 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79      requested by
12cd0 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63   the format spec
12ce0 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 20 20  ification..**   
12cf0 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
12d00 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
12d10 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
12d20 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
12d30 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
12d40 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
12d50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
12d60 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
12d70 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f   char*, ...);../
12d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
12d90 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
12da0 20 53 75 62 73 79 73 74 65 6d 20 7b 46 31 37 33   Subsystem {F173
12db0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00}.**.** The SQ
12dc0 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20  Lite core  uses 
12dd0 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
12de0 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
12df0 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
12e00 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
12e10 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
12e20 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
12e30 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
12e40 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
12e50 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
12e60 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
12e70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
12e80 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
12e90 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
12ea0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
12eb0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
12ec0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ations..**.** Th
12ed0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
12ee0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
12ef0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
12f00 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
12f10 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
12f20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
12f30 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
12f40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66  parameter..** If
12f50 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
12f60 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
12f70 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
12f80 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
12f90 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
12fa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
12fb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
12fc0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
12fd0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
12fe0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
12ff0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13000 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
13010 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
13020 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  * Calling sqlite
13030 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
13040 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
13050 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
13060 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
13070 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
13080 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
13090 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
130a0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
130b0 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65   be reused.  The
130c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
130d0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
130e0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
130f0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
13100 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
13110 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
13120 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
13130 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
13140 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
13150 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
13160 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
13170 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
13180 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
13190 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
131a0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
131b0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
131c0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
131d0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
131e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
131f0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
13200 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
13210 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
13220 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
13230 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
13240 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
13250 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
13260 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
13270 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
13280 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
13290 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
132a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e   sqlite3_free().
132b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
132c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
132d0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
132e0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
132f0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
13300 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
13310 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
13320 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
13330 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13340 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
13350 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
13360 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
13370 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
13380 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  r.  If the first
13390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
133a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
133b0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
133c0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
133d0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
133e0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
133f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
13400 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
13410 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13420 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
13430 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20  ealloc()..** If 
13440 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
13450 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
13460 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
13470 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
13480 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
13490 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
134a0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
134b0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
134c0 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
134d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
134e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
134f0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 53 71 6c  ealloc()..** Sql
13500 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
13510 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
13520 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
13530 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
13540 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
13550 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
13560 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
13570 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
13580 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74  le..** If M is t
13590 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
135a0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
135b0 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
135c0 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
135d0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
135e0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
135f0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
13600 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
13610 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
13620 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
13630 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
13640 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49  n is freed..** I
13650 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
13660 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
13670 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
13680 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
13690 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
136a0 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  ** The memory re
136b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
136c0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
136d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
136e0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
136f0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
13700 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
13710 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  dary. {END}.**.*
13720 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d  * The default im
13730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
13740 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  of the memory al
13750 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
13760 65 6d 20 75 73 65 73 20 74 68 65 20 6d 61 6c 6c  em uses the mall
13770 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 0a  oc(), realloc().
13780 2a 2a 20 61 6e 64 20 66 72 65 65 28 29 20 70 72  ** and free() pr
13790 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74  ovided by the st
137a0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
137b0 2e 20 7b 46 31 37 33 38 32 7d 20 48 6f 77 65 76  . {F17382} Howev
137c0 65 72 2c 20 69 66 20 0a 2a 2a 20 53 51 4c 69 74  er, if .** SQLit
137d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
137e0 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  th the following
137f0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
13800 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  macro.**.** <blo
13810 63 6b 71 75 6f 74 65 3e 20 53 51 4c 49 54 45 5f  ckquote> SQLITE_
13820 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e  MEMORY_SIZE=<i>N
13830 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f 63 6b 71 75  NN</i> </blockqu
13840 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65  ote>.**.** where
13850 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 69 73 20 61   <i>NNN</i> is a
13860 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 20  n integer, then 
13870 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
13880 73 74 61 74 69 63 0a 2a 2a 20 61 72 72 61 79 20  static.** array 
13890 6f 66 20 61 74 20 6c 65 61 73 74 20 3c 69 3e 4e  of at least <i>N
138a0 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
138b0 73 69 7a 65 20 61 6e 64 20 75 73 65 20 74 68 61  size and use tha
138c0 74 20 61 72 72 61 79 0a 2a 2a 20 66 6f 72 20 61  t array.** for a
138d0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
138e0 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
138f0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
13900 20 20 41 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20    Additional.** 
13910 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13920 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13930 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13940 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
13950 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
13960 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
13970 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
13980 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
13990 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
139a0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
139b0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
139c0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
139d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
139e0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
139f0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
13a00 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
13a10 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
13a20 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
13a30 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
13a40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
13a50 63 61 6e 20 62 65 0a 2a 2a 20 75 73 65 64 2e 0a  can be.** used..
13a60 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
13a70 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
13a80 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
13a90 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
13aa0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
13ab0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
13ac0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
13ad0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
13ae0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
13af0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
13b00 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
13b10 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
13b20 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
13b30 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
13b40 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
13b50 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
13b60 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
13b70 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
13b80 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
13b90 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
13ba0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
13bb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
13bc0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
13bd0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
13be0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
13bf0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20  **.** {F17303}  
13c00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
13c10 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
13c20 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
13c30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 2a   a pointer to .*
13c40 2a 20 20 20 20 20 20 20 20 20 20 20 6e 65 77 6c  *           newl
13c50 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c  y checked-out bl
13c60 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ock of at least 
13c70 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
13c80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  y.**           t
13c90 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
13ca0 69 67 6e 65 64 2c 20 0a 2a 2a 20 20 20 20 20 20  igned, .**      
13cb0 20 20 20 20 20 6f 72 20 69 74 20 72 65 74 75 72       or it retur
13cc0 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73  ns NULL if it is
13cd0 20 75 6e 61 62 6c 65 20 74 6f 20 66 75 6c 66 69   unable to fulfi
13ce0 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a  ll the request..
13cf0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20  **.** {F17304}  
13d00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
13d10 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
13d20 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
13d30 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20   pointer if.**  
13d40 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65           N is le
13d50 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
13d60 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   to zero..**.** 
13d70 7b 46 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73  {F17305}  The [s
13d80 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20  qlite3_free(P)] 
13d90 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73  interface releas
13da0 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f  es memory previo
13db0 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
13dc0 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20    returned from 
13dd0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13de0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
13df0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
13e00 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69          making i
13e10 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  t available for 
13e20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  reuse..**.** {F1
13e30 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7306}  A call to
13e40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e   [sqlite3_free(N
13e50 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c  ULL)] is a harml
13e60 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
13e70 20 7b 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c   {F17310}  A cal
13e80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
13e90 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65  alloc(0,N)] is e
13ea0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
13eb0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
13ec0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13ed0 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  loc(N)]..**.** {
13ee0 46 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20  F17312}  A call 
13ef0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
13f00 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75  loc(P,0)] is equ
13f10 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
13f20 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
13f30 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
13f40 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  P)]..**.** {F173
13f50 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20  15}  The SQLite 
13f60 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74  core uses [sqlit
13f70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
13f80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13f90 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
13fa0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  and [sqlite3_fre
13fb0 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e()] for all of 
13fc0 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  its memory alloc
13fd0 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ation and.**    
13fe0 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74         deallocat
13ff0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ion needs..**.**
14000 20 7b 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b   {F17318}  The [
14010 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14020 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,N)] interface 
14030 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
14040 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
14050 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b        to a block
14060 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20   of checked-out 
14070 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
14080 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
14090 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ze.**           
140a0 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
140b0 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c  ligned, or a NUL
140c0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
140d0 20 7b 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20   {F17321}  When 
140e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
140f0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (P,N)] returns a
14100 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
14110 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20  r, it first.**  
14120 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20           copies 
14130 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65  the first K byte
14140 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f  s of content fro
14150 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77  m P into the new
14160 6c 79 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20  ly allocated.** 
14170 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
14180 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20  K is the lesser 
14190 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
141a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
141b0 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32  P..**.** {F17322
141c0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
141d0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
141e0 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
141f0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
14200 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
14210 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75   releases the bu
14220 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ffer P..**.** {F
14230 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71  17323}  When [sq
14240 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
14250 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  N)] returns NULL
14260 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69  , the buffer P i
14270 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
14280 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72  ot modified or r
14290 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c  eleased..**.** L
142a0 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
142b0 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20  * {U17350}  The 
142c0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
142d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
142e0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
142f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
14300 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20             must 
14310 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
14320 72 20 65 6c 73 65 20 61 20 70 6f 69 6e 74 65 72  r else a pointer
14330 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
14340 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
14350 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f      invocation o
14360 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
14370 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
14380 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
14390 20 68 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   has.**         
143a0 20 20 6e 6f 74 20 62 65 65 6e 20 72 65 6c 65 61    not been relea
143b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 37 33  sed..**.** {U173
143c0 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61  51}  The applica
143d0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
143e0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
143f0 70 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20  part of .**     
14400 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
14410 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
14420 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
14430 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
14440 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
14450 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
14460 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
14470 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  *.*/.void *sqlit
14480 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
14490 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
144a0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
144b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
144c0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
144d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
144e0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
144f0 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37  tatistics {F1737
14500 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
14510 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
14520 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
14530 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
14540 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
14550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
14560 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
14570 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
14580 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14590 5d 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ].** the memory 
145a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
145b0 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77 69  stem included wi
145c0 74 68 69 6e 20 74 68 65 20 53 51 4c 69 74 65 2e  thin the SQLite.
145d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
145e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 31  S:.**.** {F17371
145f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
14600 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
14610 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
14620 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
14630 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
14640 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
14650 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 0a 2a  y outstanding .*
14660 2a 20 20 20 20 20 20 20 20 20 20 28 6d 61 6c 6c  *          (mall
14670 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
14680 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ed)..**.** {F173
14690 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
146a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
146b0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
146c0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
146d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
146e0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
146f0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 0a 2a  emory_used()] .*
14700 2a 20 20 20 20 20 20 20 20 20 20 73 69 6e 63 65  *          since
14710 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
14720 6d 61 72 6b 20 77 61 73 20 6c 61 73 74 20 72 65  mark was last re
14730 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  set..**.** {F173
14740 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72  74} The values r
14750 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
14760 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
14770 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
14780 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
14790 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
147a0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
147b0 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  head.**         
147c0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
147d0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
147e0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
147f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
14800 20 20 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f            but no
14810 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
14820 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
14830 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
14840 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  brary.**        
14850 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20    routines that 
14860 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14870 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 20  )] may call..** 
14880 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54 68 65  .** {F17375} The
14890 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
148a0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
148b0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
148c0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20  value of.**     
148d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
148e0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
148f0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
14900 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14910 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
14920 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14930 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
14940 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
14950 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
14960 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
14970 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
14980 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
14990 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20  r mark.**       
149a0 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20     prior to the 
149b0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
149c0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
149d0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
149e0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
149f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
14a00 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
14a10 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
14a20 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
14a30 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
14a40 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37 33 39  Generator {F1739
14a50 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
14a60 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
14a70 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
14a80 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
14a90 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
14aa0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
14ab0 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68  random ROWIDs wh
14ac0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
14ad0 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
14ae0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
14af0 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
14b00 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
14b10 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47  ROWID.  The PRNG
14b20 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
14b30 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
14b40 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
14b50 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
14b60 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
14b70 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
14b80 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
14b90 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
14ba0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
14bb0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
14bc0 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68  .** A call to th
14bd0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
14be0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
14bf0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
14c00 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fer P..**.** The
14c10 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
14c20 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
14c30 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
14c40 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
14c50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
14c60 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
14c70 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
14c80 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
14c90 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
14ca0 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
14cb0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
14cc0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
14cd0 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73  ..** On all subs
14ce0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
14cf0 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
14d00 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
14d10 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
14d20 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
14d30 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
14d40 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
14d50 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
14d60 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  thod..**.** INVA
14d70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
14d80 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69  17392} The [sqli
14d90 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e  te3_randomness(N
14da0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  ,P)] interface w
14db0 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66  rites N bytes of
14dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67  .**          hig
14dd0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
14de0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f  -randomness into
14df0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f   buffer P..*/.vo
14e00 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
14e10 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
14e20 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
14e30 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
14e40 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
14e50 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31  on Callbacks {F1
14e60 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2500}.**.** This
14e70 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
14e80 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
14e90 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
14ea0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14ec0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
14ed0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14ee0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
14ef0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
14f00 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
14f10 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
14f20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
14f30 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
14f40 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
14f50 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
14f60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
14f70 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
14f80 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
14f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
14fa0 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
14fb0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
14fc0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
14fd0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
14fe0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
14ff0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
15000 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
15010 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
15020 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15030 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
15040 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
15050 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
15060 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
15070 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
15080 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
15090 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
150a0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
150b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
150c0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
150d0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
150e0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
150f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
15100 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
15110 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
15120 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
15130 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
15140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
15150 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
15160 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
15170 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
15180 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
15190 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
151a0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
151b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
151c0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
151d0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
151e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
151f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
15200 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
15210 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
15220 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
15230 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
15240 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
15250 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
15260 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15270 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
15280 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
15290 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
152a0 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20  ed is ok.  When 
152b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
152c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
152d0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
152e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
152f0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
15300 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
15310 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
15320 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
15330 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
15340 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
15350 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
15360 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74  is denied.  If t
15370 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
15380 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
15390 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
153a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
153b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
153c0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
153d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
153e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
153f0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
15400 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
15410 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
15420 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
15430 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
15440 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
15450 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
15460 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
15470 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
15480 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
15490 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
154a0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
154b0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
154c0 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
154d0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
154e0 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ble..**.** The f
154f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15500 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
15510 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
15520 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 74 68  opy of.** the th
15530 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
15540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
15550 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
15560 74 65 72 66 61 63 65 2e 0a 2a 2a 20 54 68 65 20  terface..** The 
15570 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15580 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
15590 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 0a   is an integer .
155a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  ** [SQLITE_COPY 
155b0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
155c0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
155d0 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
155e0 69 6f 6e 0a 2a 2a 20 74 6f 20 62 65 20 61 75 74  ion.** to be aut
155f0 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69  horized. The thi
15600 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
15610 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 74  .** parameters t
15620 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
15630 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
15640 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
15650 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20 61 64 64 69  contain .** addi
15660 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
15670 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
15680 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
15690 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
156a0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
156b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
156c0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
156d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
156e0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
156f0 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20  sted.** source, 
15700 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
15710 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15720 73 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  s do not try to 
15730 61 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74  access data.** t
15740 68 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74  hat they are not
15750 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
15760 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
15770 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65   not try to.** e
15780 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
15790 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
157a0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
157b0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
157c0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
157d0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
157e0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
157f0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
15800 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
15810 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
15820 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
15830 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
15840 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
15850 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
15860 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
15870 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
15880 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
15890 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
158a0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
158b0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
158c0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
158d0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
158e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
158f0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
15900 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
15910 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
15920 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
15930 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
15940 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
15950 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
15960 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
15970 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
15980 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
15990 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
159a0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
159b0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
159c0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
159d0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
159e0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
159f0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
15a00 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
15a10 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
15a20 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
15a30 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
15a40 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
15a50 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
15a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15a70 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
15a80 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
15a90 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
15aa0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
15ab0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
15ac0 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
15ad0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
15ae0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
15af0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
15b00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
15b10 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15b20 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ault..**.** Note
15b30 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
15b40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
15b50 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
15b60 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ring .** [sqlite
15b70 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
15b80 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
15b90 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
15ba0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
15bb0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
15bc0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
15bd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15be0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
15bf0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  TS:.**.** {F1250
15c00 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
15c10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44  set_authorizer(D
15c20 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
15c30 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20   registers a.** 
15c40 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69           authori
15c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
15c60 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
15c70 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  ction D..**.** {
15c80 46 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68  F12502} The auth
15c90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15ca0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
15cb0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
15cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69  .**          bei
15cd0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 0a 2a  ng compiled.**.*
15ce0 2a 20 7b 46 31 32 35 30 33 7d 20 49 66 20 74 68  * {F12503} If th
15cf0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
15d00 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
15d10 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
15d20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
15d30 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
15d40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
15d50 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 68  [SQLITE_DENY] th
15d60 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
15d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
15d80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
15d90 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
15da0 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20  t caused.**     
15db0 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69       the authori
15dc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  zer callback to 
15dd0 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77  run shall fail w
15de0 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
15df0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
15e00 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  ] error code and
15e10 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
15e20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
15e30 2a 0a 2a 2a 20 7b 46 31 32 35 30 34 7d 20 57 68  *.** {F12504} Wh
15e40 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  en the authorize
15e50 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
15e60 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
15e70 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
15e80 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69            descri
15e90 62 65 64 20 69 73 20 63 6f 64 65 64 20 6e 6f 72  bed is coded nor
15ea0 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  mally..**.** {F1
15eb0 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61  2505} When the a
15ec0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15ed0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
15ee0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
15ef0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
15f00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
15f10 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
15f20 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20  all that caused 
15f30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15f40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15f50 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
15f60 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20   fail.**        
15f70 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54    with an [SQLIT
15f80 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
15f90 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ode and an error
15fa0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
15fb0 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20       explaining 
15fc0 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64  that access is d
15fd0 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  enied..**.** {F1
15fe0 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74  2506} If the aut
15ff0 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68  horizer code (th
16000 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
16010 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
16020 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  r.**          ca
16030 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49  llback) is [SQLI
16040 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65  TE_READ] and the
16050 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16060 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
16070 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16080 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
16090 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
160a0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
160b0 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ted to.**       
160c0 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c     insert a NULL
160d0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
160e0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
160f0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
16100 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
16110 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
16120 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
16130 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  n returned..**.*
16140 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68  * {F12507} If th
16150 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
16160 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
16170 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
16180 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
16190 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
161a0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
161b0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  han [SQLITE_READ
161c0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  ], then.**      
161d0 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20      a return of 
161e0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
161f0 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
16200 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44  ect as [SQLITE_D
16210 45 4e 59 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31  ENY]. .**.** {F1
16220 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20  2510} The first 
16230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16240 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16250 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
16260 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
16270 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
16280 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
16290 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
162a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
162b0 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68  *.** {F12511} Th
162c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
162d0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
162e0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
162f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53   .**          [S
16300 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
16310 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
16320 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
16330 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
16340 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
16350 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
16360 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20  ** {F12512} The 
16370 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
16380 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
16390 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
163a0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
163b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
163c0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
163d0 61 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ain .**         
163e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
163f0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
16400 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
16410 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rized..**.** {F1
16420 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20  2520} Each call 
16430 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  to [sqlite3_set_
16440 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76  authorizer()] ov
16450 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20  errides the.**  
16460 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76          any prev
16470 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64  iously installed
16480 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
16490 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20 4e 55  ** {F12521} A NU
164a0 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65  LL authorizer me
164b0 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68  ans that no auth
164c0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  orization.**    
164d0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
164e0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
164f0 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20 64 65   {F12522} The de
16500 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72  fault authorizer
16510 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   is NULL..*/.int
16520 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
16530 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
16540 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
16550 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
16560 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
16570 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16580 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
16590 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
165a0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
165b0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
165c0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 46   Return Codes {F
165d0 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12590}.**.** The
165e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
165f0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
16600 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
16610 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
16620 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
16630 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
16640 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
16650 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
16660 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
16670 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
16680 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
16690 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
166a0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
166b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
166c0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
166d0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
166e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
166f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
16700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16710 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
16720 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
16730 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
16740 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
16750 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
16760 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
16770 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
16780 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
16790 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
167a0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
167b0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b  r Action Codes {
167c0 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12550}.**.** Th
167d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
167e0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
167f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
16800 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
16810 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
16820 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
16830 72 69 7a 65 72 20 63 65 72 74 61 69 6e 20 53 51  rizer certain SQ
16840 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
16850 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
16860 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
16870 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
16880 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
16890 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
168a0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
168b0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
168c0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
168d0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
168e0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
168f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16900 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
16910 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
16920 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
16930 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
16940 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
16950 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 0a 2a  tion is to be .*
16960 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
16970 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
16980 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
16990 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
169a0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
169b0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
169c0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
169d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
169e0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
169f0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
16a00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16a10 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
16a20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
16a30 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
16a40 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
16a50 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
16a60 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
16a70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  ", .** etc.) if 
16a80 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
16a90 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
16aa0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
16ab0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
16ac0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16ad0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
16ae0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
16af0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
16b00 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
16b10 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
16b20 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
16b30 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
16b40 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74 6f 70  tly from .** top
16b50 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
16b60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
16b70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31  S:.**.** {F12551
16b80 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
16b90 61 6d 65 74 65 72 20 74 6f 20 61 6e 20 0a 2a 2a  ameter to an .**
16ba0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
16bb0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16bc0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
16bd0 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77 61  allback] is alwa
16be0 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  ys an integer.**
16bf0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
16c00 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69  E_COPY | authori
16c10 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73  zer code] that s
16c20 70 65 63 69 66 69 65 73 20 77 68 61 74 20 61 63  pecifies what ac
16c30 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
16c40 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
16c50 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
16c60 35 35 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64  552} The 3rd and
16c70 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
16c80 74 6f 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20  to the .**      
16c90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
16ca0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
16cb0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
16cc0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a  back function].*
16cd0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
16ce0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
16cf0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
16d00 6f 6e 20 77 68 69 63 68 20 0a 2a 2a 20 20 20 20  on which .**    
16d10 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
16d20 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
16d30 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73  code] is used as
16d40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16d50 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
16d60 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61  2553} The 5th pa
16d70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
16d80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
16d90 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
16da0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
16db0 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65  callback] is the
16dc0 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   name.**        
16dd0 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73    of the databas
16de0 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69  e (example: "mai
16df0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e  n", "temp", etc.
16e00 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
16e10 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34 7d 20  .**.** {F12554} 
16e20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
16e30 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  r to the.**     
16e40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
16e50 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
16e60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16e70 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a  ck] is the name.
16e80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
16e90 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
16ea0 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
16eb0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
16ec0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
16ed0 20 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74    the access att
16ee0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
16ef0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
16f00 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
16f10 66 72 6f 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20  from .**        
16f20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20    top-level SQL 
16f30 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
16f40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16f50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16f60 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
16f70 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
16f80 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
16f90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
16fa0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
16fb0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
16fc0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16fd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16fe0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
16ff0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
17000 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17010 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17020 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17030 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
17040 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
17050 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17060 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17070 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17080 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
17090 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
170a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
170b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
170c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
170d0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
170e0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
170f0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
17100 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17120 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
17130 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
17140 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
17150 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17160 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17170 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
17180 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
17190 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
171a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
171b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
171c0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
171d0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
171e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
171f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17200 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17210 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
17220 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
17230 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17240 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17260 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
17270 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
17280 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17290 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
172a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
172b0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
172c0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
172d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
172e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
172f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17300 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
17310 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
17320 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
17330 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
17340 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17350 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
17360 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
17370 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
17380 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17390 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
173a0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
173b0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
173c0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
173d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
173e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
173f0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
17400 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
17410 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17420 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17430 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
17440 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
17450 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
17460 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
17470 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17480 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
17490 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
174a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
174b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
174c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
174d0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
174e0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
174f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17500 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17510 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17520 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
17530 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
17540 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
17550 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
17560 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
17570 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
17580 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
17590 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
175a0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
175b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
175c0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
175d0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
175e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
175f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17600 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17610 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
17620 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
17630 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
17640 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17660 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
17670 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
17680 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
17690 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
176a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
176b0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
176c0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
176d0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
176e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
176f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17700 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
17710 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
17720 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
17730 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17740 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
17750 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
17760 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
17770 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
17780 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
177a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
177b0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
177c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
177d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
177e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
177f0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
17800 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
17810 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17820 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17830 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17840 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
17850 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
17860 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
17870 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17880 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
17890 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
178a0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
178b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
178c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
178d0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
178e0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
178f0 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
17900 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
17910 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17920 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
17930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
17940 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
17950 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
17960 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
17970 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
17980 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d  nctions {F12280}
17990 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
179a0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
179b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
179c0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
179d0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
179e0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
179f0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
17a00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
17a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
17a20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
17a30 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
17a40 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
17a50 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
17a60 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
17a70 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
17a80 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
17a90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
17aa0 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
17ab0 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d  k returns a UTF-
17ac0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
17ad0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17ae0 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20   text.** as the 
17af0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
17b00 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
17b10 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61  .  Additional ca
17b20 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a  llbacks occur.**
17b30 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
17b40 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
17b50 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
17b60 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
17b70 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
17b80 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
17b90 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
17ba0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
17bb0 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 63 61 6c  ..** .** The cal
17bc0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
17bd0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
17be0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
17bf0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
17c00 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
17c10 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
17c20 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
17c30 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
17c40 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
17c50 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
17c60 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
17c70 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
17c80 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
17c90 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
17ca0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   to run..**.** T
17cb0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
17cc0 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
17cd0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
17ce0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
17cf0 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
17d00 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
17d10 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65  oval in a future
17d20 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20   release..**.** 
17d30 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f  The trigger repo
17d40 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66  rting feature of
17d50 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
17d60 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ack is considere
17d70 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  d.** experimenta
17d80 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
17d90 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
17da0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
17db0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74  releases..** Fut
17dc0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
17dd0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
17de0 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20  o add new trace 
17df0 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 69 6e 76  callback .** inv
17e00 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ocations..**.** 
17e10 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
17e20 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63  * {F12281} The c
17e30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17e40 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
17e50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
17e60 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
17e70 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20  whenever an SQL 
17e80 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
17e90 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74  begins to execut
17ea0 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
17eb0 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69    whenever a tri
17ec0 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20  gger subprogram 
17ed0 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
17ee0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  run..**.** {F122
17ef0 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  82} Each call to
17f00 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
17f10 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
17f20 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
17f30 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
17f40 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ed trace callbac
17f50 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33  k..**.** {F12283
17f60 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63  } A NULL trace c
17f70 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73  allback disables
17f80 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   tracing..**.** 
17f90 7b 46 31 32 32 38 34 7d 20 54 68 65 20 66 69 72  {F12284} The fir
17fa0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
17fb0 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
17fc0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
17fd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70  *          the p
17fe0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
17ff0 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
18000 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
18010 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ace()]..**.** {F
18020 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e  12285} The secon
18030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
18040 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
18050 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
18060 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
18070 64 20 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f  d UTF8 string co
18080 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69  ntaining the ori
18090 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20  ginal text.**   
180a0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51         of the SQ
180b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
180c0 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74  t was passed int
180d0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
180e0 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
180f0 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
18100 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51  valent, or an SQ
18110 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61  L comment indica
18120 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69  ting the beginni
18130 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
18140 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  f a trigger subp
18150 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rogram..**.** {F
18160 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
18170 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
18180 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
18190 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69  te3_profile()] i
181a0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
181b0 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51        as each SQ
181c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
181d0 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  shes..**.** {F12
181e0 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
181f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18200 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
18210 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
18220 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72            the 3r
18230 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
18240 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
18250 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  )]..**.** {F1228
18260 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  9} The second pa
18270 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
18280 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
18290 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
182a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
182b0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
182c0 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  at contains the 
182d0 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66  complete text of
182e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
182f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
18300 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
18310 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
18320 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
18330 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
18340 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a  equivalent..**.*
18350 2a 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74  * {F12290} The t
18360 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
18370 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 20 63  o the profile  c
18380 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73  allback is an es
18390 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20  timate.**       
183a0 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72     of the number
183b0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20   of nanoseconds 
183c0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
183d0 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a  me required to.*
183e0 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74  *          run t
183f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
18400 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66   from start to f
18410 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  inish..*/.void *
18420 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
18430 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
18440 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
18450 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
18460 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
18470 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
18480 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
18490 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
184a0 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
184b0 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
184c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
184d0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
184e0 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31  Callbacks {F1291
184f0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
18500 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
18510 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
18520 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
18530 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
18540 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
18550 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
18560 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
18570 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
18580 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
18590 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
185a0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
185b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
185c0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
185d0 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20 69 6e   for this .** in
185e0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
185f0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
18600 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
18610 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
18620 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
18630 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
18640 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
18650 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
18660 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
18670 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
18680 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
18690 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
186a0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69  tton on a GUI di
186b0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
186c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
186d0 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65 20 63  * {F12911} The c
186e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
186f0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
18700 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
18710 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20  _handler()].**  
18720 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
18730 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
18740 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
18750 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
18760 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18770 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
18780 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20 70 72   {F12912} The pr
18790 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
187a0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
187b0 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74  for every N virt
187c0 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ual.**          
187d0 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c  machine opcodes,
187e0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
187f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18800 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
18810 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
18820 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
18830 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73   call that regis
18840 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
18850 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20    the callback. 
18860 20 3c 74 6f 64 6f 3e 57 68 61 74 20 69 66 20 4e   <todo>What if N
18870 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 3f   is less than 1?
18880 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
18890 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72  12913} The progr
188a0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73  ess callback its
188b0 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65  elf is identifie
188c0 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a  d by the third.*
188d0 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
188e0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
188f0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18900 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ()]..**.** {F129
18910 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61  14} The fourth a
18920 72 67 75 6d 65 6e 74 20 5b 73 71 6c 69 74 65 33  rgument [sqlite3
18930 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
18940 72 28 29 5d 20 69 73 20 61 0a 2a 2a 2a 20 20 20  r()] is a.***   
18950 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74        void point
18960 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
18970 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
18980 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ck.**          f
18990 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
189a0 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
189b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20  .**.** {F12915} 
189c0 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
189d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
189e0 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
189f0 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
18a00 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e 67 20  N opcodes being 
18a10 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 20 20 20  executed,.**    
18a20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 70        then the p
18a30 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
18a40 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65   is never invoke
18a50 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 0a 2a 2a 20  d. {END}.** .** 
18a60 7b 46 31 32 39 31 36 7d 20 45 76 65 72 79 20 63  {F12916} Every c
18a70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
18a80 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18a90 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
18aa0 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70  overwrites any p
18ab0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
18ac0 65 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61  ered progress ha
18ad0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ndler..**.** {F1
18ae0 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f  2917} If the pro
18af0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
18b00 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74  llback is NULL t
18b10 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a  hen no progress.
18b20 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64  **          hand
18b30 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  ler is invoked..
18b40 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49  **.** {F12918} I
18b50 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
18b60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18b70 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
18b80 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20  han 0, then.**  
18b90 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61          the beha
18ba0 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71  vior is a if [sq
18bb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18bc0 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c  )] had been call
18bd0 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
18be0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
18bf0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
18c00 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
18c10 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
18c20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
18c30 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
18c40 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46  se Connection {F
18c50 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12700}.**.** The
18c60 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
18c70 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
18c80 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
18c90 61 6d 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e 20  ame.** is given 
18ca0 62 79 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  by the filename 
18cb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
18cc0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
18cd0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
18ce0 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 66 6f  d as UTF-8.** fo
18cf0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
18d00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18d10 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
18d20 73 20 55 54 46 2d 31 36 0a 2a 2a 20 69 6e 20 74  s UTF-16.** in t
18d30 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
18d40 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
18d50 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
18d60 41 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  An [sqlite3*] ha
18d70 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 20  ndle is usually 
18d80 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
18d90 62 2c 20 65 76 65 6e 0a 2a 2a 20 69 66 20 61 6e  b, even.** if an
18da0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
18db0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
18dc0 6f 6e 20 69 73 20 69 66 20 53 51 4c 69 74 65 20  on is if SQLite 
18dd0 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 74 6f 20  is unable.** to 
18de0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
18df0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
18e00 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 20 61 20  ite3] object, a 
18e10 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  NULL will.** be 
18e20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
18e30 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
18e40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
18e50 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
18e60 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
18e70 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
18e80 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 0a 2a  nd/or created).*
18e90 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  * successfully, 
18ea0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  then [SQLITE_OK]
18eb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
18ec0 74 68 65 72 77 69 73 65 20 61 6e 0a 2a 2a 20 65  therwise an.** e
18ed0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
18ee0 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b  urned.  The.** [
18ef0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
18f00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
18f10 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69  rmsg16()]  routi
18f20 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
18f30 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
18f40 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
18f50 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
18f60 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
18f70 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
18f80 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
18f90 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
18fa0 54 46 2d 38 20 69 66 0a 2a 2a 20 5b 73 71 6c 69  TF-8 if.** [sqli
18fb0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
18fc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18fd0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  )] is called and
18fe0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
18ff0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
19000 64 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  der if [sqlite3_
19010 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
19020 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
19030 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
19040 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
19050 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
19060 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
19070 65 64 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ed with the [sql
19080 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68  ite3*] handle sh
19090 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
190a0 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 0a 2a   by passing it.*
190b0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  * to [sqlite3_cl
190c0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
190d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
190e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
190f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
19100 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
19110 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
19120 33 5f 6f 70 65 6e 28 29 5d 20 0a 2a 2a 20 65 78  3_open()] .** ex
19130 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
19140 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
19150 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
19160 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
19170 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
19180 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
19190 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
191a0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
191b0 63 61 6e 20 62 65 0a 2a 2a 20 6f 6e 65 20 6f 66  can be.** one of
191c0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
191d0 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
191e0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 0a 2a 2a 20  EN_READONLY].** 
191f0 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
19200 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 0a 2a 2a  EN_READWRITE].**
19210 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
19220 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
19230 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
19240 45 41 54 45 5d 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  EATE].** </ol>.*
19250 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 76  *.** The first v
19260 61 6c 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64  alue opens the d
19270 61 74 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c  atabase read-onl
19280 79 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  y. .** If the da
19290 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 20  tabase does not 
192a0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
192b0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
192c0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 73  turned..** The s
192d0 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65  econd option ope
192e0 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
192f0 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
19300 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
19310 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
19320 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66  ng only if.** if
19330 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
19340 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20 49  te protected.  I
19350 6e 20 65 69 74 68 65 72 20 63 61 73 65 20 74 68  n either case th
19360 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 6d 75  e database.** mu
19370 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
19380 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 69 73 20   or an error is 
19390 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 74  returned.  The t
193a0 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a 20 6f  hird option.** o
193b0 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
193c0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
193d0 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20 63 72  d writing and cr
193e0 65 61 74 65 73 20 69 74 20 69 66 20 69 74 20 64  eates it if it d
193f0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72 65 61  oes.** not alrea
19400 64 79 20 65 78 69 73 74 2e 0a 2a 2a 20 54 68 65  dy exist..** The
19410 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 73 20 69   third options i
19420 73 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  s behavior that 
19430 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
19440 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
19450 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
19460 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
19470 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
19480 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
19490 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
194a0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
194b0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
194c0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 74  ns shown above t
194d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
194e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
194f0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
19500 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
19510 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
19520 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65 6d 6f 72 79  ate.** in-memory
19530 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
19540 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
19550 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
19560 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 64 61 74 61  n-memory.** data
19570 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
19580 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
19590 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
195a0 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
195b0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  .** version of S
195c0 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61 6b 65  QLite might make
195d0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
195e0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
195f0 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62 65 67  ames.** that beg
19600 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
19610 63 68 61 72 61 63 74 65 72 2e 20 20 49 74 20 69  character.  It i
19620 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
19630 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20 64 61  at .** when a da
19640 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
19650 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  really does begi
19660 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20 74 68  n with.** ":" th
19670 61 74 20 79 6f 75 20 70 72 65 66 69 78 20 74 68  at you prefix th
19680 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
19690 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b 65 20  a pathname like 
196a0 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f 69 64  "./" to.** avoid
196b0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
196c0 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
196d0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
196e0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
196f0 76 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a  vate temporary.*
19700 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
19710 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
19720 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
19730 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
19740 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
19750 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
19760 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
19770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
19780 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
19790 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
197a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
197b0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
197c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
197d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
197e0 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
197f0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
19800 73 79 73 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72  system .** inter
19810 66 61 63 65 20 74 68 61 74 20 74 68 65 20 6e 65  face that the ne
19820 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
19830 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
19840 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  .  If the.** fou
19850 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
19860 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
19870 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
19880 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a 2a   [sqlite3_vfs].*
19890 2a 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  * object is used
198a0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
198b0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
198c0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
198d0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
198e0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
198f0 6e 74 0a 2a 2a 20 6f 66 20 5b 73 71 6c 69 74 65  nt.** of [sqlite
19900 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
19910 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19920 5d 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ] must be UTF-8,
19930 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
19940 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
19950 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
19960 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
19970 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
19980 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
19990 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
199a0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
199b0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
199c0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  em into.** [sqli
199d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
199e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
199f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
19a00 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
19a10 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  701} The [sqlite
19a20 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
19a30 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
19a40 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
19a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19a60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72  )] interfaces cr
19a70 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20  eate a new.**   
19a80 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
19a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73   connection] ass
19aa0 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
19ab0 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74           the dat
19ac0 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e  abase file given
19ad0 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20   in their first 
19ae0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
19af0 20 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66 69   {F12702} The fi
19b00 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
19b10 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
19b20 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  s UTF-8.**      
19b30 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33      for [sqlite3
19b40 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71  _open()] and [sq
19b50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
19b60 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a   and as UTF-16.*
19b70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68  *          in th
19b80 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
19b90 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
19ba0 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
19bb0 2a 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75 63  * {F12703} A suc
19bc0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
19bd0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f  on of [sqlite3_o
19be0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
19bf0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 0a 2a 2a 20  _open16()], .** 
19c00 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
19c10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19c20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72  writes a pointer
19c30 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
19c40 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
19c50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f  connection] into
19c60 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46   *ppDb..**.** {F
19c70 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69  12704} The [sqli
19c80 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
19c90 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
19ca0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
19cb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
19cc0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
19cd0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
19ce0 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c  K] upon success,
19cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19d00 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
19d10 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
19d20 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
19d30 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75  12706} The defau
19d40 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
19d50 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
19d60 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
19d70 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
19d80 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
19d90 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
19da0 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  v2()] will be UT
19db0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  F-8..**.** {F127
19dc0 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  07} The default 
19dd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
19de0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
19df0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
19e00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
19e10 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69  te3_open16()] wi
19e20 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ll be UTF-16..**
19e30 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65  .** {F12709} The
19e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46   [sqlite3_open(F
19e50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  ,D)] interface i
19e60 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a  s equivalent to.
19e70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
19e80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
19e90 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65  ,G,0)] where the
19ea0 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a   G parameter is.
19eb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19ec0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
19ed0 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  TE]|[SQLITE_OPEN
19ee0 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  _CREATE]..**.** 
19ef0 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68 65 20  {F12711} If the 
19f00 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
19f10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19f20 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
19f30 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
19f40 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
19f50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
19f60 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74  LY] then the dat
19f70 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a  abase is opened.
19f80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
19f90 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a  reading only..**
19fa0 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20  .** {F12712} If 
19fb0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
19fc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
19fd0 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
19fe0 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
19ff0 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1a000 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1a010 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68  ADWRITE] then th
1a020 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a030 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1a040 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1a050 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1a060 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67  , or for reading
1a070 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20   only if the.** 
1a080 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73           file is
1a090 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1a0a0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1a0b0 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  g system..**.** 
1a0c0 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68 65 20  {F12713} If the 
1a0d0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1a0e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28  sqlite3_open(v2(
1a0f0 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20  F,D,G,V)] omits 
1a100 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1a110 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1a120 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
1a130 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
1a140 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
1a150 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
1a160 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1a180 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74  ** {F12714} If t
1a190 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1a1a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1a1b0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1a1c0 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1a1d0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1a1e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1a1f0 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1a200 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a210 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1a220 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65  ously exist, the
1a230 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  n an attempt is 
1a240 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61  made to create a
1a250 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
1a260 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61  nitialize the da
1a270 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tabase..**.** {F
1a280 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69  12717} If the fi
1a290 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1a2a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1a2b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1a2c0 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
1a2d0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
1a2e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22  _open_v2()] is "
1a2f0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1a300 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20  an private,.**  
1a310 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
1a320 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  l, in-memory dat
1a330 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
1a340 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1a350 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion..**         
1a360 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1a370 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1a380 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a390 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1a3a0 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1a3b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1a3c0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  odo>.**.** {F127
1a3d0 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  19} If the filen
1a3e0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ame is NULL or a
1a3f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1a400 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a  then a private,.
1a410 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
1a420 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61  meral on-disk da
1a430 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
1a440 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20  reated..**      
1a450 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1a460 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1a470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a480 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1a490 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1a4a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1a4b0 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46  </todo>.**.** {F
1a4c0 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61  12721} The [data
1a4d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a4e0 20 63 72 65 61 74 65 64 20 62 79 20 0a 2a 2a 20   created by .** 
1a4f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a500 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1a510 56 29 5d 20 77 69 6c 6c 20 75 73 65 20 74 68 65  V)] will use the
1a520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a530 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1a540 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
1a550 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
1a560 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1a570 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1a580 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1a590 20 69 73 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   is V is a NULL 
1a5a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
1a5b0 46 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74  F12723} Two [dat
1a5c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a5d0 20 7c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   | database conn
1a5e0 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68  ections] will sh
1a5f0 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63  are a common cac
1a600 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
1a610 66 20 62 6f 74 68 20 77 65 72 65 20 6f 70 65 6e  f both were open
1a620 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
1a630 20 56 46 53 0a 2a 2a 20 20 20 20 20 20 20 20 20   VFS.**         
1a640 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a650 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
1a660 63 68 65 20 7c 20 73 68 61 72 65 64 20 63 61 63  che | shared cac
1a670 68 65 20 6d 6f 64 65 20 77 61 73 20 65 6e 61 62  he mode was enab
1a680 6c 65 64 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  led] and.**     
1a690 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c       if both fil
1a6a0 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65  enames compare e
1a6b0 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d  qual using memcm
1a6c0 70 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  p().**          
1a6d0 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65  after having bee
1a6e0 6e 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74  n processed by t
1a6f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
1a700 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d  | xFullPathname]
1a710 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 20 20   method of.**   
1a720 20 20 20 20 20 20 20 74 68 65 20 56 46 53 2e 0a         the VFS..
1a730 2a 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  **.*/.int sqlite
1a740 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1a750 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a760 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a770 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a780 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a790 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1a7a0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a7b0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a7c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1a7d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1a7e0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1a7f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1a800 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1a810 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1a820 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a830 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1a850 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1a860 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a870 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a880 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a890 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a8a0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1a8b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a8c0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1a8d0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1a8e0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1a8f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1a900 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1a910 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1a920 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1a930 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1a940 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1a950 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a 2a 2a  ages {F12800}.**
1a960 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a970 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1a980 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1a990 6e 75 6d 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49  numeric.** [SQLI
1a9a0 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
1a9b0 6f 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ode] or [SQLITE_
1a9c0 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
1a9d0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1a9e0 65 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f  e].** for the mo
1a9f0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1aa00 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1aa10 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
1aa20 2a 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5d  * with [sqlite3]
1aa30 20 68 61 6e 64 6c 65 20 27 64 62 27 2e 20 49 66   handle 'db'. If
1aa40 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
1aa50 6c 20 66 61 69 6c 65 64 20 62 75 74 20 74 68 65  l failed but the
1aa60 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
1aa70 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
1aa80 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
1aa90 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
1aaa0 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  3_errcode().** i
1aab0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1aac0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1aad0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1aae0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1aaf0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ab00 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1ab10 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ab20 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1ab30 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36  er UTF8 or UTF16
1ab40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1ab50 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * Memory to hold
1ab60 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1ab70 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
1ab80 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
1ab90 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1aba0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
1abb0 64 20 74 6f 20 77 6f 72 72 79 20 77 69 74 68 20  d to worry with 
1abc0 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1abd0 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1abe0 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1abf0 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1ac00 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1ac10 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1ac20 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1ac30 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1ac40 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1ac50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1ac60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 31  S:.**.** {F12801
1ac70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
1ac80 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72  rrcode(D)] inter
1ac90 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1aca0 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20   numeric.**     
1acb0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 20       [SQLITE_OK 
1acc0 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f  | result code] o
1acd0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
1ace0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
1acf0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
1ad00 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  lt code].**     
1ad10 20 20 20 20 20 66 6f 72 20 74 68 65 20 6d 6f 73       for the mos
1ad20 74 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  t recently faile
1ad30 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1ad40 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20   associated.**  
1ad50 20 20 20 20 20 20 20 20 77 69 74 68 20 5b 64 61          with [da
1ad60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ad70 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
1ad80 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
1ad90 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64  3_errmsg(D)] and
1ada0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1adb0 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  16(D)].**       
1adc0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1add0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1ade0 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20  guage text that 
1adf0 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20  describes.**    
1ae00 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20        the error 
1ae10 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65  in the mostly re
1ae20 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
1ae30 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a  terface call,.**
1ae40 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65            encode
1ae50 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 38  d as either UTF8
1ae60 20 6f 72 20 55 54 46 31 36 20 72 65 73 70 65 63   or UTF16 respec
1ae70 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tively..**.** {F
1ae80 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e  12807} The strin
1ae90 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
1aea0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1aeb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1aec0 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
1aed0 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64         are valid
1aee0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1aef0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1af00 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   call..**.** {F1
1af10 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41  2808} Calls to A
1af20 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  PI routines that
1af30 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61   do not return a
1af40 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  n error code.** 
1af50 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c           (exampl
1af60 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  e: [sqlite3_data
1af70 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f  _count()]) do no
1af80 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  t.**          ch
1af90 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
1afa0 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72  ode or message r
1afb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1afc0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1afd0 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c  errcode()], [sql
1afe0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1aff0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1b000 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  sg16()]..**.** {
1b010 46 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63  F12809} Interfac
1b020 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20  es that are not 
1b030 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1b040 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20  a specific.**   
1b050 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1b060 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78   connection] (ex
1b070 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20  amples:.**      
1b080 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72      [sqlite3_mpr
1b090 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69  intf()] or [sqli
1b0a0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1b0b0 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20  d_cache()].**   
1b0c0 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68         do not ch
1b0d0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 20  ange the values 
1b0e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1b0f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1b100 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
1b110 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
1b120 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1b130 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  msg16()]..*/.int
1b140 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1b150 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1b160 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1b170 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1b180 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1b190 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1b1a0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1b1b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1b1c0 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1b1d0 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 4b  ct {F13000}.** K
1b1e0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1b1f0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1b200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b210 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1b220 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1b230 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1b240 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1b250 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 0a 2a 2a  tement.  This.**
1b260 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
1b270 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
1b280 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
1b290 65 6e 74 22 20 6f 72 20 61 20 0a 2a 2a 20 22 63  ent" or a .** "c
1b2a0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1b2b0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
1b2c0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
1b2d0 22 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 6c 69  "..** .** The li
1b2e0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1b2f0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1b300 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1b310 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1b320 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1b330 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1b340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b350 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1b360 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1b370 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1b380 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
1b390 70 61 72 61 6d 65 74 65 72 73 20 75 73 69 6e 67  parameters using
1b3a0 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
1b3b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
1b3c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 69 6e 74  lite3_bind_* int
1b3d0 65 72 66 61 63 65 73 5d 2e 0a 2a 2a 20 3c 6c 69  erfaces]..** <li
1b3e0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
1b3f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1b400 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
1b410 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1b420 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
1b430 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1b440 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1b450 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
1b460 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
1b470 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
1b480 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1b490 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
1b4a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1b4b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1b4c0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
1b4d0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
1b4e0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
1b4f0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
1b500 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
1b510 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1b520 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
1b530 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1b540 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
1b550 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1b560 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
1b570 69 74 73 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a  its {F12760}.**.
1b580 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1b590 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1b5a0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1b5b0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1b5c0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1b5d0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1b5e0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1b5f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b600 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1b610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b620 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1b630 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1b640 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1b650 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b660 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1b670 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1b680 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1b690 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1b6a0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1b6b0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1b6c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1b6d0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1b6e0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1b6f0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1b700 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b710 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  e old limit..**.
1b720 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69  ** If the new li
1b730 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1b740 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1b750 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1b760 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d  ..** For the lim
1b770 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
1b780 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
1b790 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20  there is a hard 
1b7a0 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73  upper.** bound s
1b7b0 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d  et by a compile-
1b7c0 74 69 6d 65 20 43 2d 70 72 65 70 72 6f 63 65 73  time C-preproces
1b7d0 73 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51  s macro named SQ
1b7e0 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a  LITE_MAX_XYZ..**
1b7f0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1b800 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1b810 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1b820 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20  ".).** Attempts 
1b830 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1b840 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1b850 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1b860 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1b870 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1b880 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74  hard upper limit
1b890 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65  ..**.** Run time
1b8a0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
1b8b0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
1b8c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
1b8d0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
1b8e0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
1b8f0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
1b900 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
1b910 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
1b920 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
1b930 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
1b940 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
1b950 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1b960 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62  ght be a.** webb
1b970 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
1b980 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
1b990 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
1b9a0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
1b9b0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
1b9c0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
1b9d0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
1b9e0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
1b9f0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
1ba00 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
1ba10 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
1ba20 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
1ba30 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
1ba40 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
1ba50 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
1ba60 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
1ba70 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
1ba80 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
1ba90 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
1baa0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
1bab0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
1bac0 74 74 61 63 68 2e 20 20 44 65 76 65 6c 6f 70 65  ttach.  Develope
1bad0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
1bae0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
1baf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1bb00 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
1bb10 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
1bb20 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
1bb30 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
1bb40 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1bb50 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
1bb60 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
1bb70 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
1bb80 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
1bb90 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
1bba0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
1bbb0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1bbc0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  e is currently c
1bbd0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
1bbe0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
1bbf0 62 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e  bject.** to chan
1bc00 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77 69  ge or removal wi
1bc10 74 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74 69  thout prior noti
1bc20 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ce..**.** INVARI
1bc30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
1bc40 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  762} A successfu
1bc50 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1bc60 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1bc70 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20   where V is.**  
1bc80 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65          positive
1bc90 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
1bca0 20 20 20 20 20 20 20 20 20 6c 69 6d 69 74 20 6f           limit o
1bcb0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
1bcc0 6e 73 74 72 75 63 74 20 43 20 69 6e 20 5b 64 61  nstruct C in [da
1bcd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bce0 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
1bcf0 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f   to the lesser o
1bd00 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
1bd10 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
1bd20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20  the size.**     
1bd30 20 20 20 20 20 6f 66 20 43 20 74 68 61 74 20 69       of C that i
1bd40 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
1bd50 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  -time..**.** {F1
1bd60 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
1bd70 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1bd80 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1bd90 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
1bda0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
1bdb0 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
1bdc0 74 65 20 6f 66 20 5b 64 61 74 61 62 61 73 65 20  te of [database 
1bdd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e  connection] D un
1bde0 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
1bdf0 46 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73  F12769} A succes
1be00 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1be10 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1be20 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a  V)] returns the.
1be30 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
1be40 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f  e of the limit o
1be50 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
1be60 6e 73 74 72 75 63 74 20 43 20 69 6e 0a 2a 2a 20  nstruct C in.** 
1be70 20 20 20 20 20 20 20 20 20 69 6e 20 5b 64 61 74           in [dat
1be80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1be90 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72  ] D as it was pr
1bea0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
1beb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1bec0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1bed0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1bee0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1bef0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1bf00 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
1bf10 7b 46 31 32 37 39 30 7d 0a 2a 2a 20 4b 45 59 57  {F12790}.** KEYW
1bf20 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1bf30 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61  egory} {limit ca
1bf40 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 20 0a 2a 2a  tegories}.** .**
1bf50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1bf60 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1bf70 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
1bf80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bf90 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
1bfa0 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
1bfb0 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
1bfc0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
1bfd0 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
1bfe0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
1bff0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
1c000 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
1c010 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
1c020 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1c030 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c040 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1c050 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 62 6c  .** string or bl
1c060 6f 62 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  ob or table row.
1c070 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
1c080 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1c090 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1c0a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1c0b0 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
1c0c0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1c0d0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1c0e0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
1c0f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c100 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c110 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
1c120 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
1c130 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
1c140 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
1c150 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  T or the maximum
1c160 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1c170 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
1c180 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
1c190 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
1c1a0 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
1c1b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c1c0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1c1d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c1e0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1c1f0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1c200 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1c210 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1c220 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1c230 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1c240 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c250 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c260 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1c270 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1c280 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1c290 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1c2a0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1c2b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c2c0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1c2d0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1c2e0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1c2f0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1c300 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1c310 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1c320 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1c330 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1c340 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
1c350 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c360 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1c370 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
1c380 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1c390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1c3a0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1c3b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c3c0 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64  mber of attached
1c3d0 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e   databases.</dd>
1c3e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c3f0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1c400 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
1c410 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c420 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
1c430 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
1c440 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f  nt to the LIKE o
1c450 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74  r.** GLOB operat
1c460 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ors.</dd>.**.** 
1c470 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c480 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c490 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c4a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c4b0 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20  of variables in 
1c4c0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c4d0 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20   that can.** be 
1c4e0 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  bound.</dd>.** <
1c4f0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1c500 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c510 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1c520 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
1c530 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
1c540 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
1c550 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
1c560 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1c570 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
1c580 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
1c590 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c5a0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
1c5b0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
1c5c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c5d0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1c5e0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
1c5f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c600 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
1c610 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
1c620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c630 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
1c640 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
1c650 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c660 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
1c670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
1c680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c690 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1c6a0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
1c6b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c6c0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1c6d0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
1c6e0 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  9../*.** CAPI3RE
1c6f0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1c700 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
1c710 31 33 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  13010}.**.** To 
1c720 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
1c730 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
1c740 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
1c750 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
1c760 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
1c770 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
1c780 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a 2a 2a 20  outines. .**.** 
1c790 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1c7a0 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20 5b 64  nt "db" is an [d
1c7b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c7c0 6f 6e 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  on] .** obtained
1c7d0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61   from a prior ca
1c7e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
1c7f0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1c800 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f  _open_v2()].** o
1c810 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1c820 36 28 29 5d 2e 20 0a 2a 2a 20 54 68 65 20 73 65  6()]. .** The se
1c830 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a  cond argument "z
1c840 53 71 6c 22 20 69 73 20 74 68 65 20 73 74 61 74  Sql" is the stat
1c850 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
1c860 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
1c870 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1c880 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
1c890 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c8a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1c8b0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
1c8c0 6e 74 65 72 66 61 63 65 73 20 75 73 65 73 20 55  nterfaces uses U
1c8d0 54 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33  TF-8 and sqlite3
1c8e0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
1c8f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c900 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
1c910 54 46 2d 31 36 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  TF-16. {END}.**.
1c920 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  ** If the nByte 
1c930 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1c940 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  .** than zero, t
1c950 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1c960 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
1c970 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1c980 2e 0a 2a 2a 20 49 66 20 6e 42 79 74 65 20 69 73  ..** If nByte is
1c990 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1c9a0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1c9b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c9c0 0a 2a 2a 20 62 79 74 65 73 20 72 65 61 64 20 66  .** bytes read f
1c9d0 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
1c9e0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1c9f0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
1ca00 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
1ca10 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
1ca20 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
1ca30 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
1ca40 6f 72 20 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65  or .** the nByte
1ca50 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
1ca60 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
1ca70 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
1ca80 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
1ca90 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
1caa0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
1cab0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
1cac0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
1cad0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
1cae0 67 65 20 74 6f 20 62 65 20 68 61 64 20 62 79 20  ge to be had by 
1caf0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
1cb00 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
1cb10 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1cb20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1cb30 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1cb40 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1cb50 64 69 6e 67 3c 2f 69 3e 20 0a 2a 2a 20 74 68 65  ding</i> .** the
1cb60 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1cb70 62 79 74 65 73 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a  bytes.{END}.**.*
1cb80 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  * *pzTail is mad
1cb90 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1cba0 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73  e first byte pas
1cbb0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1cbc0 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74  .** first SQL st
1cbd0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1cbe0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1cbf0 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68   only compile th
1cc00 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65  e first.** state
1cc10 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1cc20 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1cc30 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61   pointing to wha
1cc40 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63  t remains.** unc
1cc50 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
1cc60 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
1cc70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
1cc80 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
1cc90 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1cca0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
1ccb0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1ccc0 33 5f 73 74 65 70 28 29 5d 2e 20 20 4f 72 20 69  3_step()].  Or i
1ccd0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
1cce0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 0a  ror, *ppStmt is.
1ccf0 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20  ** set to NULL. 
1cd00 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65   If the input te
1cd10 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1cd20 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1cd30 0a 2a 2a 20 69 73 20 61 6e 64 20 65 6d 70 74 79  .** is and empty
1cd40 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
1cd50 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
1cd60 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
1cd70 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d 20 54  L..** {U13018} T
1cd80 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
1cd90 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
1cda0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
1cdb0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   the.** compiled
1cdc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1cdd0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
1cde0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1cdf0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1ce00 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a  ed with it..**.*
1ce10 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  * On success, [S
1ce20 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1ce30 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1ce40 65 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20  e an .** [error 
1ce50 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1ce60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1ce70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ce80 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1ce90 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1cea0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1ceb0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1cec0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1ced0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1cee0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1cef0 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1cf00 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1cf10 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1cf20 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1cf30 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
1cf40 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1cf50 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1cf60 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1cf70 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1cf80 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1cf90 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1cfa0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a  a copy of the .*
1cfb0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1cfc0 65 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20  ext. {END} This 
1cfd0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
1cfe0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
1cff0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
1d000 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
1d010 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
1d020 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1d030 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
1d040 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1d050 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1d060 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1d070 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1d080 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1d090 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1d0a0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1d0b0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1d0c0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1d0d0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1d0e0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1d0f0 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
1d100 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
1d110 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
1d120 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
1d130 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
1d140 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1d150 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
1d160 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1d170 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
1d180 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
1d190 62 65 68 61 76 69 6f 72 2c 20 0a 2a 2a 20 5b 53  behavior, .** [S
1d1a0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73  QLITE_SCHEMA] is
1d1b0 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72   now a fatal err
1d1c0 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20  or.  Calling.** 
1d1d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d1e0 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c  _v2()] again wil
1d1f0 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a  l not make the.*
1d200 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e  * error go away.
1d210 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c    Note: use [sql
1d220 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74  ite3_errmsg()] t
1d230 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a  o find the text.
1d240 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e  ** of the parsin
1d250 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73  g error that res
1d260 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49  ults in an [SQLI
1d270 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72  TE_SCHEMA] retur
1d280 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 3c 2f 6c 69  n. {END}.** </li
1d290 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1d2a0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1d2b0 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74  curs, .** [sqlit
1d2c0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1d2d0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1d2e0 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b  e detailed .** [
1d2f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
1d300 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
1d310 63 6f 64 65 73 5d 2e 20 0a 2a 2a 20 54 68 65 20  codes]. .** The 
1d320 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1d330 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  was that [sqlite
1d340 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1d350 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1d360 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45  neric.** [SQLITE
1d370 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1d380 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c  ode and you woul
1d390 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1d3a0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a   second call to.
1d3b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
1d3c0 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  t()] in order to
1d3d0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1d3e0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1d3f0 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69  e problem..** Wi
1d400 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1d410 61 72 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20  are interfaces, 
1d420 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1d430 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1d440 72 6f 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e  ror is.** return
1d450 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1d460 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1d470 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1d480 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  TS:.**.** {F1301
1d490 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1d4a0 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c  prepare(db,zSql,
1d4b0 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
1d4c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1d4d0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1d4e0 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  l,...)] interfac
1d4f0 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  es interpret the
1d500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
1d510 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20  t in their zSql 
1d520 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46  parameter as UTF
1d530 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  -8..**.** {F1301
1d540 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1d550 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71  prepare16(db,zSq
1d560 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1d570 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1d580 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 62  _prepare16_v2(db
1d590 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1d5a0 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1d5b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1d5c0 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1d5d0 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1d5e0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1d5f0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1d600 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d  ..**.** {F13013}
1d610 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1d620 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1d630 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1d640 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
1d650 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
1d660 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
1d670 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1d680 2c 20 74 68 65 6e 20 53 51 4c 20 74 65 78 74 20  , then SQL text 
1d690 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1d6a0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1d6b0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1d6c0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1d6d0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
1d6e0 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1d6f0 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1d700 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d710 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1d720 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1d730 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1d740 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1d750 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1d760 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  t nBytes bytes.*
1d770 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74  *          SQL t
1d780 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d  ext is read from
1d790 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zSql..**.** {F1
1d7a0 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65  3015} In [sqlite
1d7b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1d7c0 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29  zSql,N,P,pzTail)
1d7d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1d7e0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ts.**          i
1d7f0 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74  f the zSql input
1d800 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d   text contains m
1d810 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c  ore than one SQL
1d820 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
1d830 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69         and pzTai
1d840 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  l is not NULL, t
1d850 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
1d860 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
1d870 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1d880 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
1d890 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
1d8a0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1d8b0 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20  nt in zSql..**  
1d8c0 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68          <todo>Wh
1d8d0 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20  at does *pzTail 
1d8e0 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72  point to if ther
1d8f0 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65  e is one stateme
1d900 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  nt?</todo>.**.**
1d910 20 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63 63   {F13016} A succ
1d920 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1d930 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d940 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53  v2(db,zSql,N,ppS
1d950 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  tmt,...)].**    
1d960 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20        or one of 
1d970 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69  its variants wri
1d980 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74  tes into *ppStmt
1d990 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1d9a0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1d9b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1d9c0 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65  ent] or a pointe
1d9d0 72 20 74 6f 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  r to NULL.**    
1d9e0 20 20 20 20 20 20 69 66 20 7a 53 71 6c 20 63 6f        if zSql co
1d9f0 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f  ntains nothing o
1da00 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73  ther than whites
1da10 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  pace or comments
1da20 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39  . .**.** {F13019
1da30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  } The [sqlite3_p
1da40 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74  repare_v2()] int
1da50 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20 76  erface and its v
1da60 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a  ariants return.*
1da70 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
1da80 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70  TE_OK] or an app
1da90 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
1daa0 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75  code] upon failu
1dab0 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32  re..**.** {F1302
1dac0 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74  1} Before [sqlit
1dad0 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53  e3_prepare(db,zS
1dae0 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c  ql,nByte,ppStmt,
1daf0 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a  pzTail)] or its.
1db00 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 72 69  **          vari
1db10 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20  ants returns an 
1db20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65  error (any value
1db30 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1db40 49 54 45 5f 4f 4b 5d 29 0a 2a 2a 20 20 20 20 20  ITE_OK]).**     
1db50 20 20 20 20 20 69 74 20 66 69 72 73 74 20 73 65       it first se
1db60 74 73 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55  ts *ppStmt to NU
1db70 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
1db80 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1db90 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1dba0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1dbb0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1dbc0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1dbd0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1dbe0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1dbf0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1dc00 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1dc10 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1dc20 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1dc30 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1dc40 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1dc50 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1dc60 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1dc70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1dc80 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1dc90 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1dca0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1dcb0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1dcc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dcd0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1dce0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1dcf0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1dd00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1dd10 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1dd20 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1dd30 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1dd40 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1dd50 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1dd60 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1dd70 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1dd80 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1dd90 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1dda0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1ddb0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1ddc0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1ddd0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1dde0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1ddf0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1de00 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1de10 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1de20 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1de30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1de40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1de50 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1de60 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1de70 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1de80 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1de90 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1dea0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1deb0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1dec0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ded0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1dee0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1def0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1df00 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1df10 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1df20 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1df30 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1df40 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1df50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1df60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1df70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1df80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1df90 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1dfa0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1dfb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1dfc0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1dfd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1dfe0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1dff0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1e000 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1e010 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1e020 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1e030 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1e040 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1e050 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1e060 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1e070 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1e080 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1e090 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52  /*.** CAPIREF: R
1e0a0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
1e0b0 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d  ent SQL {F13100}
1e0c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1e0d0 72 66 61 63 65 20 20 63 61 6e 20 62 65 20 75 73  rface  can be us
1e0e0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1e0f0 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1e100 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1e110 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1e120 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1e130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1e140 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1e150 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d 20  .**.** {F13101} 
1e160 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
1e170 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73   statement] pass
1e180 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20  ed as .**       
1e190 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65     the an argume
1e1a0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  nt to [sqlite3_s
1e1b0 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
1e1c0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ed.**          c
1e1d0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1e1e0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1e1f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
1e200 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e210 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e220 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1e230 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1e240 71 6c 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72  ql()] function r
1e250 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1e260 20 74 6f 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   to a.**        
1e270 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
1e280 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  d string contain
1e290 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ing a UTF-8 rend
1e2a0 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ering.**        
1e2b0 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61    of the origina
1e2c0 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  l SQL statement.
1e2d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 32 7d 20  .**.** {F13102} 
1e2e0 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
1e2f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73   statement] pass
1e300 65 64 20 61 73 20 0a 2a 2a 20 20 20 20 20 20 20  ed as .**       
1e310 20 20 20 74 68 65 20 61 6e 20 61 72 67 75 6d 65     the an argume
1e320 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  nt to [sqlite3_s
1e330 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
1e340 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ed.**          c
1e350 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1e360 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1e370 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
1e380 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1e390 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
1e3a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
1e3b0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1e3c0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1e3d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e3e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d 20  .**.** {F13103} 
1e3f0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
1e400 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1e410 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64  sql(S)] is valid
1e420 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20   until the.**   
1e430 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
1e440 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
1e450 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b   deleted using [
1e460 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1e470 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  (S)]..*/.const c
1e480 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1e490 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1e4a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1e4b0 50 49 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63  PI3REF:  Dynamic
1e4c0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1e4d0 20 4f 62 6a 65 63 74 20 20 7b 46 31 35 30 30 30   Object  {F15000
1e4e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1e4f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e500 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1e510 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e520 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1e530 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1e540 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1e550 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1e560 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1e570 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1e580 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1e590 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  e..** SQLite use
1e5a0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1e5b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1e5c0 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a 20  it stores.  .** 
1e5d0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
1e5e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e5f0 62 6a 65 63 74 73 20 63 61 6e 20 62 65 0a 2a 2a  bjects can be.**
1e600 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1e610 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1e620 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1e630 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1e640 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1e650 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1e660 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1e670 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1e680 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1e690 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1e6a0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1e6b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1e6c0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1e6d0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1e6e0 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1e6f0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1e700 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1e710 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1e720 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1e730 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1e740 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1e750 66 69 65 73 20 0a 2a 2a 20 77 68 65 74 68 65 72  fies .** whether
1e760 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1e770 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1e780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1e790 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1e7a0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1e7b0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1e7c0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1e7d0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1e7e0 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1e7f0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1e800 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1e810 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1e820 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1e830 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1e840 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1e850 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1e860 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1e870 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1e880 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1e890 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1e8a0 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  h SQLITE_THREADS
1e8b0 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b  AFE=0 and with [
1e8c0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1e8d0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
1e8e0 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  0).** then there
1e8f0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1e900 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 70 72  on between.** pr
1e910 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1e920 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e930 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1e940 64 20 74 68 65 79 20 63 61 6e 20 62 65 0a 2a 2a  d they can be.**
1e950 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
1e960 65 61 62 6c 65 2e 20 20 48 6f 77 65 76 65 72 2c  eable.  However,
1e970 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1e980 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1e990 0a 2a 2a 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  .** is recommend
1e9a0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1e9b0 69 6f 6e 73 20 6d 61 6b 65 20 74 68 65 20 64 69  ions make the di
1e9c0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1e9d0 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 70 72 6f  n.** between pro
1e9e0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1e9f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1ea00 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1ea10 6e 20 69 66 0a 2a 2a 20 74 68 65 79 20 61 72 65  n if.** they are
1ea20 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65 64   single threaded
1ea30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ea40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ea50 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1ea60 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1ea70 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1ea80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a  ementation of .*
1ea90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
1eaa0 65 5f 66 75 6e 63 74 69 6f 6e 20 7c 20 61 70 70  e_function | app
1eab0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1eac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 0a   SQL functions].
1ead0 2a 2a 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  ** are protected
1eae0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1eaf0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1eb00 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1eb10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1eb20 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1eb30 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1eb40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1eb50 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1eb60 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1eb70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1eb80 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1eb90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1eba0 61 6c 75 65 28 29 5d 2e 20 20 0a 2a 2a 20 54 68  alue()].  .** Th
1ebb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1ebc0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1ebd0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1ebe0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1ebf0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1ec00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ec10 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1ec20 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1ec30 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1ec40 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1ec50 52 45 46 3a 20 20 53 51 4c 20 46 75 6e 63 74 69  REF:  SQL Functi
1ec60 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1ec70 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a  t {F16001}.**.**
1ec80 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
1ec90 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
1eca0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
1ecb0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
1ecc0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
1ecd0 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
1ece0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1ecf0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20 6f 62  e3_context.** ob
1ed00 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73 20 66  ject is always f
1ed10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1ed20 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  o .** [sqlite3_c
1ed30 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 7c  reate_function |
1ed40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1ed50 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1ed60 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
1ed70 69 63 61 74 69 6f 6e 65 64 2d 64 65 66 69 6e 65  icationed-define
1ed80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1ed90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1eda0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1edb0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1edc0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  into calls to.**
1edd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1ede0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
1edf0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
1ee00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
1ee10 63 6f 6e 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 5b  context()],.** [
1ee20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1ee30 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1ee40 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1ee50 64 6c 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  dle()],.** [sqli
1ee60 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1ee70 29 5d 2c 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  )], and/or [sqli
1ee80 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1ee90 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1eea0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1eeb0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1eec0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1eed0 50 49 33 52 45 46 3a 20 20 42 69 6e 64 69 6e 67  PI3REF:  Binding
1eee0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1eef0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
1ef00 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e  F13500}.**.** In
1ef10 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
1ef20 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1ef30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ef40 20 61 6e 64 20 69 74 73 0a 2a 2a 20 76 61 72 69   and its.** vari
1ef50 61 6e 74 73 2c 20 6c 69 74 65 72 61 6c 73 20 6d  ants, literals m
1ef60 61 79 20 62 65 20 72 65 70 6c 61 63 65 20 62 79  ay be replace by
1ef70 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20   a parameter in 
1ef80 6f 6e 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  one.** of these 
1ef90 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  forms:.**.** <ul
1efa0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
1efb0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
1efc0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
1efd0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
1efe0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
1eff0 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d  .** In the param
1f000 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e  eter forms shown
1f010 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e   above NNN is an
1f020 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
1f030 2c 0a 2a 2a 20 56 56 56 20 61 6c 70 68 61 2d 6e  ,.** VVV alpha-n
1f040 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72  umeric parameter
1f050 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 76 61   name..** The va
1f060 6c 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61  lues of these pa
1f070 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
1f080 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
1f090 6d 65 74 65 72 20 6e 61 6d 65 73 22 0a 2a 2a 20  meter names".** 
1f0a0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1f0b0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1f0c0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1f0d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1f0e0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1f0f0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ere..**.** The f
1f100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1f110 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1f120 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
1f130 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70 6f  lways.** is a po
1f140 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1f150 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
1f160 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
1f170 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1f180 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
1f190 73 20 76 61 72 69 61 6e 74 73 2e 20 54 68 65 20  s variants. The 
1f1a0 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
1f1b0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1f1c0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
1f1d0 20 74 6f 20 62 65 20 73 65 74 2e 20 54 68 65 0a   to be set. The.
1f1e0 2a 2a 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ** first paramet
1f1f0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
1f200 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
1f210 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61  same named.** pa
1f220 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
1f230 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
1f240 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
1f250 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
1f260 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
1f270 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
1f280 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1f290 2e 20 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  . .** The index 
1f2a0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1f2b0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1f2c0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1f2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f2e0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f2f0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
1f300 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
1f310 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1f320 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1f330 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
1f340 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1f350 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1f360 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
1f370 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
1f380 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1f390 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
1f3a0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
1f3b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
1f3c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1f3d0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
1f3e0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f3f0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  ..**.** In those
1f400 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1f410 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1f420 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1f430 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65  lue is the numbe
1f440 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e  r of bytes.** in
1f450 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1f460 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1f470 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e  e value is the n
1f480 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1f490 73 3c 2f 75 3e 0a 2a 2a 20 69 6e 20 74 68 65 20  s</u>.** in the 
1f4a0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1f4b0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1f4c0 65 72 73 2e 20 0a 2a 2a 20 49 66 20 74 68 65 20  ers. .** If the 
1f4d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1f4e0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
1f4f0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
1f500 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
1f510 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1f520 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
1f530 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1f540 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
1f550 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1f560 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1f570 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
1f580 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
1f590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f5a0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
1f5b0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
1f5c0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
1f5d0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
1f5e0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
1f5f0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1f600 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
1f610 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
1f620 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
1f630 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
1f640 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
1f650 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
1f660 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
1f670 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
1f680 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
1f690 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1f6a0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74  e freed..** If t
1f6b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1f6c0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
1f6d0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
1f6e0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
1f6f0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
1f700 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
1f710 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
1f720 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
1f730 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1f740 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
1f750 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
1f760 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1f770 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1f780 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1f790 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1f7a0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1f7b0 20 7a 65 72 6f 73 2e 20 20 41 20 7a 65 72 6f 62   zeros.  A zerob
1f7c0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1f7d0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1f7e0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1f7f0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1f800 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
1f810 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
1f820 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
1f830 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
1f840 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
1f850 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
1f860 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
1f870 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
1f880 65 6e 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  en using .** [sq
1f890 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1f8a0 7c 20 69 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42  | increment BLOB
1f8b0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20   I/O] routines. 
1f8c0 41 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61  A negative.** va
1f8d0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
1f8e0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
1f8f0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
1f900 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
1f910 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f920 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
1f930 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
1f940 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f950 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
1f960 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
1f970 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
1f980 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
1f990 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f9a0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
1f9b0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
1f9c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
1f9d0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
1f9e0 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
1f9f0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
1fa00 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
1fa10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1fa20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1fa30 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1fa40 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
1fa50 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
1fa60 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
1fa70 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1fa80 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1fa90 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1faa0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1fab0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
1fac0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1fad0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1fae0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
1faf0 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
1fb00 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
1fb10 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1fb20 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
1fb30 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
1fb40 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
1fb50 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
1fb60 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
1fb70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
1fb80 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
1fb90 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
1fba0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
1fbb0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
1fbc0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
1fbd0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
1fbe0 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
1fbf0 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
1fc00 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
1fc10 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
1fc20 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
1fc30 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1fc40 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
1fc50 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
1fc60 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
1fc70 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
1fc80 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1fc90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1fca0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1fcb0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1fcc0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
1fcd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1fce0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1fcf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
1fd00 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1fd10 35 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  506} The [sqlite
1fd20 33 5f 70 72 65 70 61 72 65 20 7c 20 53 51 4c 20  3_prepare | SQL 
1fd30 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1fd40 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 0a 2a  er] recognizes.*
1fd50 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e  *          token
1fd60 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 20 22  s of the forms "
1fd70 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
1fd80 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
1fd90 22 40 56 56 56 22 0a 2a 2a 20 20 20 20 20 20 20  "@VVV".**       
1fda0 20 20 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65     as SQL parame
1fdb0 74 65 72 73 2c 20 77 68 65 72 65 20 4e 4e 4e 20  ters, where NNN 
1fdc0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
1fdd0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  of one or more.*
1fde0 2a 20 20 20 20 20 20 20 20 20 20 64 69 67 69 74  *          digit
1fdf0 73 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20  s and where VVV 
1fe00 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
1fe10 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 0a  of one or more .
1fe20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 70 68  **          alph
1fe30 61 6e 75 6d 65 72 69 63 20 63 68 61 72 61 63 74  anumeric charact
1fe40 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69  ers or "::" opti
1fe50 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
1fe60 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  by.**          a
1fe70 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1fe80 6e 67 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64  ng no spaces and
1fe90 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1fea0 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a  n parentheses..*
1feb0 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68  *.** {F13509} Th
1fec0 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20  e initial value 
1fed0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
1fee0 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ter is NULL..**.
1fef0 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20  ** {F13512} The 
1ff00 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20  index of an "?" 
1ff10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1ff20 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e   one larger than
1ff30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ff40 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
1ff50 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
1ff60 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20  to the left, or 
1ff70 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  1 if.**         
1ff80 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20   the "?" is the 
1ff90 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
1ffa0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ameter..**.** {F
1ffb0 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78  13515} The index
1ffc0 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51   of an "?NNN" SQ
1ffd0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  L parameter is t
1ffe0 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a  he integer NNN..
1fff0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54  **.** {F13518} T
20000 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
20010 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f  :VVV", "$VVV", o
20020 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72  r "@VVV" SQL par
20030 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
20040 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
20050 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c  s the index of l
20060 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e  eftmost occurren
20070 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ces of the same.
20080 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
20090 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f  meter, or one mo
200a0 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67  re than the larg
200b0 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61  est index over a
200c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ll.**          p
200d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
200e0 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73   left if this is
200f0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
20100 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rence.**        
20110 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65    of this parame
20120 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69  ter, or 1 if thi
20130 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  s is the leftmos
20140 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
20150 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20  ** {F13521} The 
20160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20170 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   | SQL statement
20180 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 20   compiler] fail 
20190 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
201a0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47   an [SQLITE_RANG
201b0 45 5d 20 65 72 72 6f 72 20 69 66 20 74 68 65 20  E] error if the 
201c0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
201d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
201e0 20 20 20 20 20 20 69 73 20 6c 65 73 73 20 74 68        is less th
201f0 61 6e 20 31 20 6f 72 20 67 72 65 61 74 65 72 20  an 1 or greater 
20200 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 41 58 5f  than SQLITE_MAX_
20210 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 2e  VARIABLE_NUMBER.
20220 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20  .**.** {F13524} 
20230 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
20240 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
20250 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56  lite3_bind(S,N,V
20260 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
20270 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65     associate the
20280 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c   value V with al
20290 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
202a0 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20   having an.**   
202b0 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20         index of 
202c0 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  N in the [prepar
202d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
202e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20  .**.** {F13527} 
202f0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
20300 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
20310 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e  lite3_bind(S,N,.
20320 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
20330 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
20340 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73  calls with the s
20350 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20  ame values of S 
20360 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  and N..**.** {F1
20370 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65  3530} Bindings e
20380 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73  stablished by [s
20390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
203a0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
203b0 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  S,...)].**      
203c0 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f      persist acro
203d0 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ss calls to [sql
203e0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a  ite3_reset(S)]..
203f0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49  **.** {F13533} I
20400 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20410 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
20420 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
20430 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20440 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
20450 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
20460 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
20470 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
20480 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
20490 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a  nds the first L.
204a0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65  **          byte
204b0 73 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 6f 72  s of the blob or
204c0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
204d0 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a  to by V, when L.
204e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
204f0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
20500 2a 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63  ** {F13536} In c
20510 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20520 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
20530 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ,L,D)] or.**    
20540 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
20550 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
20560 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
20570 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a  nds characters.*
20580 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
20590 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  V through the fi
205a0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
205b0 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67  er when L is neg
205c0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
205d0 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3539} In calls t
205e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
205f0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
20600 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
20610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20620 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
20630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
20640 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20650 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
20660 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63  en D is the spec
20670 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
20680 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
20690 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65  _STATIC], SQLite
206a0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
206b0 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20  e value V.**    
206c0 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e        is held in
206d0 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65   static unmanage
206e0 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c  d space that wil
206f0 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  l not change.** 
20700 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20           during 
20710 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
20720 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a  the binding..**.
20730 2a 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63  ** {F13542} In c
20740 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20750 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
20760 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
20770 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
20780 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
20790 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
207a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
207b0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
207c0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
207d0 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
207e0 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
207f0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
20800 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d  ], the routine m
20810 61 6b 65 73 20 61 20 0a 2a 2a 20 20 20 20 20 20  akes a .**      
20820 20 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79      private copy
20830 20 6f 66 20 56 20 76 61 6c 75 65 20 62 65 66 6f   of V value befo
20840 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
20850 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20 49 6e  *.** {F13545} In
20860 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20870 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
20880 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
20890 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
208a0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
208b0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
208c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
208d0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
208e0 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
208f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
20900 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74           a funct
20910 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f  ion, SQLite invo
20920 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f  kes that functio
20930 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65  n to destroy the
20940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56 20 76  .**          V v
20950 61 6c 75 65 20 61 66 74 65 72 20 69 74 20 68 61  alue after it ha
20960 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
20970 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2a   the V value..**
20980 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49 6e 20  .** {F13548} In 
20990 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
209a0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
209b0 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61  S,N,V,L)] the va
209c0 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20  lue bound.**    
209d0 20 20 20 20 20 20 69 73 20 61 20 62 6c 6f 62 20        is a blob 
209e0 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61  of L bytes, or a
209f0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f   zero-length blo
20a00 62 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69  b if L is negati
20a10 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35  ve..**.** {F1355
20a20 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  1} In calls to [
20a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
20a40 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56  ue(S,N,V)] the V
20a50 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a   argument may.**
20a60 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74            be eit
20a70 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64  her a [protected
20a80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
20a90 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20  object or an.** 
20aa0 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74           [unprot
20ab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20ac0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  lue] object..*/.
20ad0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20ae0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
20af0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
20b00 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
20b10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
20b20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20b30 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
20b40 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
20b50 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
20b60 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
20b70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
20b80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20b90 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
20ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
20bb0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
20bc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
20bd0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
20be0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
20bf0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
20c00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20c10 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
20c20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
20c30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
20c40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
20c50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20c60 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
20c70 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
20c80 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
20c90 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
20ca0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20cb0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
20cc0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
20cd0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
20ce0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
20cf0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
20d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20d10 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
20d20 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36 30 30  rameters {F13600
20d30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
20d40 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
20d50 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
20d60 62 65 72 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  ber of SQL param
20d70 65 74 65 72 73 0a 2a 2a 20 69 6e 20 61 20 70 72  eters.** in a pr
20d80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20d90 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
20da0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
20db0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
20dc0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
20dd0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
20de0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
20df0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
20e00 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
20e10 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
20e20 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
20e30 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
20e40 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
20e50 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
20e60 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
20e70 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
20e80 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
20e90 65 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  est parameter..*
20ea0 2a 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  * For all forms 
20eb0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
20ec0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
20ed0 64 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  d to the number 
20ee0 6f 66 0a 2a 2a 20 75 6e 69 71 75 65 20 70 61 72  of.** unique par
20ef0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
20f00 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
20f10 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 20 74 68  NNN are used, th
20f20 65 72 65 20 6d 61 79 0a 2a 2a 20 62 65 20 67 61  ere may.** be ga
20f30 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a  ps in the list..
20f40 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
20f50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20f60 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
20f70 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
20f80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
20f90 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
20fa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20fb0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
20fc0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
20fd0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 30 31  S:.**.** {F13601
20fe0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
20ff0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
21000 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  unt(S)] interfac
21010 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
21020 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73        the larges
21030 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53  t index of all S
21040 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  QL parameters in
21050 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
21060 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21070 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66  ment] S, or 0 if
21080 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63   S.**          c
21090 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
210a0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
210b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
210c0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
210d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
210e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
210f0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
21100 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30  arameter {F13620
21110 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
21120 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
21130 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
21140 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
21150 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
21160 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
21170 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
21180 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
21190 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
211a0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
211b0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
211c0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
211d0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
211e0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
211f0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
21200 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
21210 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
21220 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
21230 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
21240 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
21250 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
21260 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
21270 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
21280 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
21290 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
212a0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
212b0 65 20 6e 6f 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  e no name..**.**
212c0 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20   The first host 
212d0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
212e0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
212f0 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65   0..**.** If the
21300 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20   value n is out 
21310 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
21320 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65  he n-th paramete
21330 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
21340 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
21350 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65  eturned.  The re
21360 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
21370 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74 68  .** always in th
21380 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
21390 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
213a0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
213b0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
213c0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
213d0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
213e0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
213f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
21400 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
21410 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21420 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
21430 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
21440 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21450 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21460 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
21470 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21480 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
21490 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
214a0 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20 54  **.** {F13621} T
214b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
214c0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
214d0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
214e0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
214f0 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64      a UTF-8 rend
21500 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d  ering of the nam
21510 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  e of the SQL par
21520 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20  ameter in.**    
21530 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
21540 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76  statement] S hav
21550 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a  ing index N, or.
21560 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c  **          NULL
21570 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
21580 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69  SQL parameter wi
21590 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66  th index N or if
215a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
215b0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
215c0 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e  index N is an an
215d0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
215e0 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  r "?"..*/.const 
215f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
21600 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
21610 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21620 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
21630 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
21640 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
21650 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b  h A Given Name {
21660 46 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13640}.**.** Re
21670 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
21680 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
21690 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
216a0 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78  e.  The.** index
216b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
216c0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
216d0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
216e0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
216f0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
21700 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21710 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a  d()].  A zero.**
21720 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
21730 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
21740 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
21750 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   The parameter.*
21760 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
21770 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
21780 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
21790 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
217a0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
217b0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
217c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
217d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
217e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
217f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
21800 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
21810 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
21820 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
21830 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
21840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21850 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21860 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21870 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d  :.**.** {F13641}
21880 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
21890 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
218a0 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ex(S,N)] interfa
218b0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
218c0 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78         the index
218d0 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65   of SQL paramete
218e0 72 20 69 6e 20 5b 70 72 65 70 61 72 65 64 20 73  r in [prepared s
218f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
21900 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61        S whose na
21910 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55  me matches the U
21920 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f  TF-8 string N, o
21930 72 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a  r 0 if there is.
21940 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d  **          no m
21950 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  atch..*/.int sql
21960 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21970 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
21980 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
21990 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
219a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
219b0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
219c0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
219d0 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36 36 30  tatement {F13660
219e0 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79  }.**.** Contrary
219f0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
21a00 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
21a10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
21a20 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20 74  s not.** reset t
21a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
21a40 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
21a50 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 70 72 65 70  ] on a .** [prep
21a60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21a70 20 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69    Use this routi
21a80 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 65 74 20 61  ne to.** reset a
21a90 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
21aa0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  rs to NULL..**.*
21ab0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
21ac0 0a 2a 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65  .** {F13661} The
21ad0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
21ae0 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74  bindings(S)] int
21af0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c  erface resets al
21b00 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  l.**          SQ
21b10 4c 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64  L parameter bind
21b20 69 6e 67 73 20 69 6e 20 5b 70 72 65 70 61 72 65  ings in [prepare
21b30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
21b40 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20  *          back 
21b50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
21b60 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
21b70 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
21b80 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
21b90 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
21ba0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
21bb0 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31  esult Set {F1371
21bc0 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0}.**.** Return 
21bd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
21be0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
21bf0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
21c00 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65   by the .** [pre
21c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21c20 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
21c30 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70  eturns 0.** if p
21c40 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73  Stmt is an SQL s
21c50 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
21c60 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
21c70 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d  ta (for .** exam
21c80 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a  ple an UPDATE)..
21c90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21ca0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d  :.**.** {F13711}
21cb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
21cc0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
21cd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
21ce0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
21cf0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
21d00 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
21d10 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
21d20 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
21d30 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
21d40 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69  ement] S, or 0 i
21d50 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
21d60 65 72 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  erate.**        
21d70 20 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a    a result set..
21d80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
21d90 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
21da0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
21db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21dc0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
21dd0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
21de0 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13720}.**.** T
21df0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
21e00 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
21e10 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
21e20 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
21e30 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
21e40 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73  et of a SELECT s
21e50 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73  tatement.  The s
21e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
21e70 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
21e80 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
21e90 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
21ea0 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20 73 74  rminated UTF8 st
21eb0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
21ec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
21ed0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
21ee0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
21ef0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
21f00 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  F16 string.  The
21f10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21f20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   is the.** [prep
21f30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21f40 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
21f50 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
21f60 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 65 63  ment..** The sec
21f70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
21f80 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62   the column numb
21f90 65 72 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f  er.  The left-mo
21fa0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 0a 2a 2a 20  st column is.** 
21fb0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
21fc0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
21fd0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
21fe0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
21ff0 72 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61  r the .** [prepa
22000 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
22010 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
22020 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22030 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  ()].** or until 
22040 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 73 71  the next call sq
22050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22060 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
22070 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a  olumn_name16().*
22080 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  * on the same co
22090 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
220a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
220b0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
220c0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
220d0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
220e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
220f0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
22100 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
22110 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
22120 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
22130 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
22140 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
22150 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
22160 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
22170 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
22180 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
22190 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
221a0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
221b0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
221c0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
221d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
221e0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
221f0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
22200 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
22210 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
22220 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
22230 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
22240 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20 41  **.** {F13721} A
22250 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
22260 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
22270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22280 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  me(S,N)].**     
22290 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72       interface r
222a0 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 0a  eturns the name.
222b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
222c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
222d0 68 65 72 65 20 30 20 69 73 20 74 68 65 20 6c 65  here 0 is the le
222e0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  ft-most column) 
222f0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
22300 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
22310 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
22320 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 0a 2a 2a  ement] S as a.**
22330 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
22340 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
22350 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  string..**.** {F
22360 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73  13723} A success
22370 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
22380 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
22390 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
223a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
223b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
223c0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
223d0 20 20 20 20 20 20 6f 66 20 74 68 65 20 4e 74 68        of the Nth
223e0 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
223f0 20 69 73 20 74 68 65 20 6c 65 66 74 2d 6d 6f 73   is the left-mos
22400 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
22410 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
22420 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
22430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22440 20 53 20 61 73 20 61 0a 2a 2a 20 20 20 20 20 20   S as a.**      
22450 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
22460 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e  ted UTF-16 strin
22470 67 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  g in the native 
22480 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
22490 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65 20 5b  * {F13724} The [
224a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
224b0 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ame()] and [sqli
224c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
224d0 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
224e0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
224f0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
22500 72 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e  r if they are un
22510 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20  able to.**      
22520 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d      allocate mem
22530 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69  ory to hold thei
22540 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20  r normal return 
22550 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  strings..**.** {
22560 46 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e  F13725} If the N
22570 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
22580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22590 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  me(S,N)] or.**  
225a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
225b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
225c0 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72  ,N)] is out of r
225d0 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ange, then the.*
225e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
225f0 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
22600 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
22610 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54 68 65  .** {F13726} The
22620 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
22630 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
22640 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  lumn_name(S,N)] 
22650 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
22660 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22670 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65  name16(S,N)] are
22680 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
22690 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   next.**        
226a0 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72    call to either
226b0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68   routine with th
226c0 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70  e same S and N p
226d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
226e0 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b        or until [
226f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22700 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
22710 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d 20 57  **.** {F13727} W
22720 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c  hen a result col
22730 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  umn of a [SELECT
22740 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74  ] statement cont
22750 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
22760 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74   an AS clause, t
22770 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20  he name of that 
22780 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64  column is the id
22790 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20  entifier.**     
227a0 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67 68       to the righ
227b0 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77  t of the AS keyw
227c0 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ord..*/.const ch
227d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
227e0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
227f0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
22800 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22810 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22830 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
22840 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
22850 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
22860 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 34  ry Result {F1374
22870 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
22880 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
22890 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
228a0 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
228b0 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
228c0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
228d0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
228e0 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
228f0 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
22900 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
22910 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
22920 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
22930 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
22940 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
22950 38 20 6f 72 20 55 54 46 31 36 20 73 74 72 69 6e  8 or UTF16 strin
22960 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
22970 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
22980 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
22990 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
229a0 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
229b0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
229c0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
229d0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
229e0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
229f0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
22a00 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
22a10 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 0a 2a  is valid until.*
22a20 2a 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  * the [prepared 
22a30 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
22a40 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a  stroyed using.**
22a50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22a60 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
22a70 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
22a80 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
22a90 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
22aa0 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
22ab0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
22ac0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
22ad0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
22ae0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
22af0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22b00 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
22b10 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
22b20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
22b30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
22b40 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
22b50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
22b60 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
22b70 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
22b80 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
22b90 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
22ba0 6e 65 64 20 62 79 20 0a 2a 2a 20 74 68 65 20 73  ned by .** the s
22bb0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
22bc0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
22bd0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
22be0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
22bf0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
22c00 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
22c10 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
22c20 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71  ssion.** or subq
22c30 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
22c40 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
22c50 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
22c60 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  e functions.** r
22c70 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 54 68 65  eturn NULL.  The
22c80 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
22c90 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
22ca0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  L if a memory.**
22cb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
22cc0 72 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  r occurs.  Other
22cd0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
22ce0 6e 20 74 68 65 20 0a 2a 2a 20 6e 61 6d 65 20 6f  n the .** name o
22cf0 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
22d00 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20 61  atabase, table a
22d10 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  nd column that q
22d20 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 63  uery result.** c
22d30 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
22d40 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
22d50 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
22d60 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
22d70 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77  hose postfixed w
22d80 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
22d90 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
22da0 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f  d strings, the o
22db0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
22dc0 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e  eturn UTF-8. {EN
22dd0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41  D}.**.** These A
22de0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
22df0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
22e00 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
22e10 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
22e20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
22e30 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72  LUMN_METADATA pr
22e40 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
22e50 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  l defined..**.**
22e60 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20   {U13751}.** If 
22e70 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
22e80 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
22e90 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
22ea0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
22eb0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
22ec0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
22ed0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
22ee0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
22ef0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
22f00 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
22f10 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
22f20 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d 20 54 68  *.** {F13741} Th
22f30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
22f40 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
22f50 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
22f60 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
22f70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
22f80 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
22f90 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
22fa0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77   database from w
22fb0 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20  hich the .**    
22fc0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
22fd0 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70   column of [prep
22fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22ff0 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  S .**          i
23000 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20  s extracted, or 
23010 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
23020 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
23030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
23040 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
23050 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
23060 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
23070 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
23080 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
23090 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
230a0 46 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c  F13742} The [sql
230b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
230c0 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  base_name16(S,N)
230d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
230e0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
230f0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
23100 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
23110 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
23120 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
23130 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
23140 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
23150 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
23160 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
23170 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
23180 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
23190 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
231a0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
231b0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
231c0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
231d0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
231e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
231f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
23200 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
23210 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
23220 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
23230 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
23240 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
23250 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
23260 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
23270 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
23280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
23290 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
232a0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
232b0 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
232c0 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
232d0 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
232e0 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
232f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23300 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
23310 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
23320 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
23330 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
23340 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
23350 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
23360 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
23370 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
23380 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
23390 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
233a0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
233b0 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69  13744} The [sqli
233c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
233d0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
233e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
233f0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
23400 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
23410 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
23420 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
23430 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
23440 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72   of the table fr
23450 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a 2a 2a  om which the .**
23460 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
23470 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b  sult column of [
23480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23490 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20 20 20  nt] S .**       
234a0 20 20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c     is extracted,
234b0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
234c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
234d0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
234e0 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
234f0 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
23500 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23510 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
23520 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
23530 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 0a  e..**          .
23540 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54 68 65 20  ** {F13745} The 
23550 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23560 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29  origin_name(S,N)
23570 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
23580 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
23590 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
235a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
235b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
235c0 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77  le column from w
235d0 68 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20  hich the .**    
235e0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
235f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70   column of [prep
23600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23610 53 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  S .**          i
23620 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20  s extracted, or 
23630 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
23640 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
23650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e  .**          gen
23660 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
23670 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
23680 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
23690 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
236a0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
236b0 2a 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b  *          .** {
236c0 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c  F13746} The [sql
236d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
236e0 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  in_name16(S,N)] 
236f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23700 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
23710 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
23720 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
23730 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
23740 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
23750 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
23760 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
23770 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  h the .**       
23780 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
23790 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65  lumn of [prepare
237a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a  d statement] S .
237b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 65  **          is e
237c0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
237d0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
237e0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a  umn of S is a.**
237f0 20 20 20 20 20 20 20 20 20 20 67 65 6e 65 72 61            genera
23800 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
23810 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
23820 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
23830 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
23840 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20  e the name..**  
23850 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33          .** {F13
23860 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20  748} The return 
23870 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20  values from.**  
23880 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
23890 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
238a0 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d 65 74  _name|column met
238b0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
238c0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
238d0 65 20 76 61 6c 69 64 0a 2a 2a 20 20 20 20 20 20  e valid.**      
238e0 20 20 20 20 66 6f 72 20 74 68 65 20 6c 69 66 65      for the life
238f0 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
23900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
23920 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
23930 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
23940 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
23950 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
23960 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
23970 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
23980 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
23990 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c   column..**.** L
239a0 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
239b0 2a 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77  * {U13751} If tw
239c0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
239d0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
239e0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
239f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23a00 61 74 61 62 61 73 65 5f 6e 61 6d 65 7c 63 6f 6c  atabase_name|col
23a10 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
23a20 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20  erfaces].**     
23a30 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 5b 70       the same [p
23a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23a50 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
23a60 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
23a70 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
23a80 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
23a90 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
23aa0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
23ab0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23ac0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
23ad0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23ae0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23af0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
23b00 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
23b10 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23b20 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
23b30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
23b40 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
23b50 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
23b60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23b70 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
23b80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
23b90 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
23ba0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
23bb0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_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 6f 72 69  lite3_column_ori
23bf0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
23c00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
23c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
23c30 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
23c40 75 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a  ult {F13760}.**.
23c50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
23c60 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
23c70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23c80 2e 20 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  . .** If this st
23c90 61 74 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c  atement is a SEL
23ca0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  ECT statement an
23cb0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
23cc0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 72 65 74 75   of the .** retu
23cd0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
23ce0 6f 66 20 74 68 61 74 20 53 45 4c 45 43 54 20 69  of that SELECT i
23cf0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
23d00 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
23d10 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
23d20 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
23d30 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
23d40 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
23d50 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
23d60 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
23d70 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
23d80 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
23d90 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
23da0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
23db0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
23dc0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
23dd0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
23de0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
23df0 6f 64 65 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a  oded.  {END} .**
23e00 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   For example, in
23e10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
23e20 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
23e30 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
23e40 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41  ARIANT);.**.** A
23e50 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
23e60 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
23e70 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
23e80 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
23e90 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e  M t1;.**.** Then
23ea0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
23eb0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
23ec0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
23ed0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a  for the second.*
23ee0 2a 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  * result column 
23ef0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
23f00 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
23f10 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
23f20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29  column.** (i==0)
23f30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ..**.** SQLite u
23f40 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
23f50 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f  time typing.  So
23f60 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
23f70 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
23f80 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
23f90 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
23fa0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
23fb0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
23fc0 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
23fd0 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
23fe0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
23ff0 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
24000 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
24010 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
24020 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
24030 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73  tic.  Type.** is
24040 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
24050 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
24060 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
24070 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
24080 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
24090 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  e values..**.** 
240a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
240b0 2a 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75  * {F13761}  A su
240c0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
240d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
240e0 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 0a  _decltype(S,N)].
240f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
24100 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
24110 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
24120 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
24130 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
24140 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74  the declared dat
24150 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62  atype of the tab
24160 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
24170 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20  ppears.**       
24180 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63      as the Nth c
24190 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20  olumn (numbered 
241a0 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
241b0 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
241c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
241d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
241e0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  t] S..**.** {F13
241f0 37 36 32 7d 20 20 41 20 73 75 63 63 65 73 73 66  762}  A successf
24200 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
24210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
24220 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20  ype16(S,N)].**  
24230 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
24240 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
24250 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
24260 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69   byte order stri
24270 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
24280 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
24290 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65  eclared datatype
242a0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
242b0 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
242c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  s.**           a
242d0 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  s the Nth column
242e0 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20   (numbered from 
242f0 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
24300 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20   set to the.**  
24310 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
24320 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
24330 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20  .**.** {F13763} 
24340 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   If N is less th
24350 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65  an 0 or N is gre
24360 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75  ater than or equ
24370 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  al to.**        
24380 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66     the number of
24390 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 5b 70 72 65   columns in [pre
243a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
243b0 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20   S.**           
243c0 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  or if the Nth co
243d0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20  lumn of S is an 
243e0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
243f0 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a  bquery rather.**
24400 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20             than 
24410 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 6f  a table column o
24420 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
24430 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
24440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
24450 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f  curs during enco
24460 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73  ding conversions
24470 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
24480 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71      calls to [sq
24490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
244a0 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  ltype(S,N)] or.*
244b0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
244c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
244d0 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74  type16(S,N)] ret
244e0 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e  urn NULL..*/.con
244f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24500 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
24510 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
24520 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
24530 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
24540 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
24550 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
24560 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  /* .** CAPI3REF:
24570 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51    Evaluate An SQ
24580 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  L Statement {F13
24590 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  200}.**.** After
245a0 20 61 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74   an [prepared st
245b0 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
245c0 6e 20 70 72 65 70 61 72 65 64 20 77 69 74 68 20  n prepared with 
245d0 61 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 65 69 74  a call.** to eit
245e0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
245f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
24600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24610 5f 76 32 28 29 5d 20 6f 72 20 74 6f 20 6f 6e 65  _v2()] or to one
24620 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 65 67 61 63   of.** the legac
24630 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
24640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
24650 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
24660 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 74 68  pare16()],.** th
24670 65 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  en this function
24680 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
24690 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
246a0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
246b0 65 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  e .** statement.
246c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
246d0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
246e0 6f 72 20 6f 66 20 74 68 69 73 20 73 71 6c 69 74  or of this sqlit
246f0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
24700 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
24710 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
24720 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
24730 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
24740 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
24750 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
24760 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
24770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24780 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
24790 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
247a0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
247b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
247c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
247d0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
247e0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
247f0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
24800 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
24810 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
24820 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
24830 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
24840 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
24850 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
24860 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  *.** In the lega
24870 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
24880 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
24890 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
248a0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 0a 2a 2a  QLITE_BUSY], .**
248b0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
248c0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
248d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
248e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
248f0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76  ..** With the "v
24900 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
24910 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
24920 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
24930 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 6f 72 20 5b  lt code].** or [
24940 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
24950 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
24960 75 6c 74 20 63 6f 64 65 5d 20 6d 69 67 68 74 20  ult code] might 
24970 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
24980 2a 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  * well..**.** [S
24990 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
249a0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
249b0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
249c0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
249d0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
249e0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
249f0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
24a00 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
24a10 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20   is a COMMIT.** 
24a20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
24a30 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
24a40 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
24a50 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
24a60 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
24a70 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
24a80 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f  ment is not a CO
24a90 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20  MMIT and occurs 
24aa0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
24ab0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
24ac0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
24ad0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
24ae0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
24af0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
24b00 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
24b10 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
24b20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
24b30 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
24b40 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
24b50 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
24b60 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
24b70 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
24b80 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
24b90 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
24ba0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
24bb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24bc0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
24bd0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
24be0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
24bf0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
24c00 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
24c10 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
24c20 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
24c30 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 0a  any data, then .
24c40 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ** [SQLITE_ROW] 
24c50 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
24c60 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
24c70 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
24c80 0a 2a 2a 20 66 6f 72 20 70 72 6f 63 65 73 73 69  .** for processi
24c90 6e 67 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72  ng by the caller
24ca0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
24cb0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
24cc0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
24cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
24ce0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
24cf0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
24d00 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
24d10 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
24d20 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
24d30 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
24d40 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
24d50 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
24d60 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
24d70 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
24d80 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
24d90 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
24da0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
24db0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
24dc0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
24dd0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
24de0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
24df0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
24e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
24e10 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
24e20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
24e30 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
24e40 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
24e50 20 28 65 78 61 6d 70 6c 65 3a 0a 2a 2a 20 5b 53   (example:.** [S
24e60 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
24e70 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
24e80 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
24e90 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
24ea0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
24eb0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
24ec0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24ed0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
24ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24ef0 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
24f00 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
24f10 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
24f20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
24f30 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
24f40 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
24f50 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
24f60 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
24f70 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
24f80 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
24f90 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
24fa0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
24fb0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
24fc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24fd0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
24fe0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
24ff0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
25000 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
25010 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 20 0a  n one that had .
25020 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
25030 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
25040 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
25050 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
25060 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
25070 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
25080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25090 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
250a0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
250b0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
250c0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
250d0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
250e0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
250f0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 0a 2a 2a  ce Alert:</b>.**
25100 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
25110 6e 74 65 72 66 61 63 65 2c 20 0a 2a 2a 20 74 68  nterface, .** th
25120 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
25130 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
25140 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
25150 72 6f 72 20 63 6f 64 65 2c 0a 2a 2a 20 5b 53 51  ror code,.** [SQ
25160 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
25170 6c 6f 77 69 6e 67 20 61 6e 79 20 65 72 72 6f 72  lowing any error
25180 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
25190 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 61 6e 64  ITE_BUSY].** and
251a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
251b0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
251c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
251d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
251e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
251f0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
25200 6e 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66  ne of the specif
25210 69 63 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ic.** [error cod
25220 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
25230 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
25240 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
25250 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
25260 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
25270 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
25280 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
25290 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
252a0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
252b0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
252c0 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
252d0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
252e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
252f0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
25300 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25310 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
25320 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
25330 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
25340 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
25350 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
25360 20 74 68 65 20 0a 2a 2a 20 6d 6f 72 65 20 73 70   the .** more sp
25370 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
25380 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
25390 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
253a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
253b0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
253c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
253d0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
253e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
253f0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d  :.**.** {F13202}
25400 20 20 49 66 20 5b 70 72 65 70 61 72 65 64 20 73    If [prepared s
25410 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72  tatement] S is r
25420 65 61 64 79 20 74 6f 20 62 65 0a 2a 2a 20 20 20  eady to be.**   
25430 20 20 20 20 20 20 20 20 72 75 6e 2c 20 74 68 65          run, the
25440 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
25450 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61  S)] advances tha
25460 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
25470 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
25480 20 20 75 6e 74 69 6c 20 74 6f 20 63 6f 6d 70 6c    until to compl
25490 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69  etion or until i
254a0 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65  t is ready to re
254b0 74 75 72 6e 20 61 6e 6f 74 68 65 72 0a 2a 2a 20  turn another.** 
254c0 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 6f 66            row of
254d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
254e0 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20  or an interrupt 
254f0 6f 72 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f  or run-time erro
25500 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
25510 7b 46 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61  {F15304}  When a
25520 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25530 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65  3_step(S)] cause
25540 73 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20  s the .**       
25550 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
25560 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 72 75  atement] S to ru
25570 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c  n to completion,
25580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
25590 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
255a0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ns [SQLITE_DONE]
255b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d  ..**.** {F15306}
255c0 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
255d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
255e0 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65  )] stops because
255f0 20 69 74 20 69 73 20 72 65 61 64 79 0a 2a 2a 20   it is ready.** 
25600 20 20 20 20 20 20 20 20 20 20 74 6f 20 72 65 74            to ret
25610 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  urn another row 
25620 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
25630 74 2c 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a  t, it returns.**
25640 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
25650 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  TE_ROW]..**.** {
25660 46 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61  F15308}  If a ca
25670 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
25680 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65  tep(S)] encounte
25690 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rs an.**        
256a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65     [sqlite3_inte
256b0 72 72 75 70 74 7c 69 6e 74 65 72 72 75 70 74 5d  rrupt|interrupt]
256c0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
256d0 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
256e0 20 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e     it returns an
256f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
25700 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20  or code that is 
25710 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20  not one of.**   
25720 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
25730 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  OK], [SQLITE_ROW
25740 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  ], or [SQLITE_DO
25750 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  NE]..**.** {F153
25760 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69  10}  If an [sqli
25770 74 65 33 5f 69 6e 74 65 72 72 75 70 74 7c 69 6e  te3_interrupt|in
25780 74 65 72 72 75 70 74 5d 20 6f 72 20 72 75 6e 2d  terrupt] or run-
25790 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20  time error.**   
257a0 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
257b0 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  uring a call to 
257c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
257d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  ].**           f
257e0 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  or a [prepared s
257f0 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61  tatement] S crea
25800 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
25810 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e         legacy in
25820 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
25830 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
25840 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
25850 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
25860 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  )] then the func
25870 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
25880 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25890 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
258a0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
258b0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
258c0 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
258d0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
258e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
258f0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
25900 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
25910 72 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37  result set {F137
25920 37 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  70}.**.** Return
25930 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
25940 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
25950 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
25960 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
25970 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
25980 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66  .** {F13771}  Af
25990 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
259a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
259b0 74 68 61 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  that returns.** 
259c0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
259d0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 5b 73 71 6c  E_ROW], the [sql
259e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
259f0 53 29 5d 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20  S)] routine.**  
25a00 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65           will re
25a10 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61  turn the same va
25a20 6c 75 65 20 61 73 20 74 68 65 0a 2a 2a 20 20 20  lue as the.**   
25a30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25a40 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
25a50 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ] function..**.*
25a60 2a 20 7b 46 31 33 37 37 32 7d 20 20 41 66 74 65  * {F13772}  Afte
25a70 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
25a80 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  S)] has returned
25a90 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
25aa0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
25ab0 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20     [SQLITE_ROW] 
25ac0 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  or before [sqlit
25ad0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
25ae0 62 65 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20  been .**        
25af0 20 20 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65     called on the
25b00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25b10 6d 65 6e 74 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  ment] for.**    
25b20 20 20 20 20 20 20 20 74 68 65 20 66 69 72 73 74         the first
25b30 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77   time since it w
25b40 61 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  as [sqlite3_prep
25b50 61 72 65 7c 70 72 65 70 61 72 65 64 5d 0a 2a 2a  are|prepared].**
25b60 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73             or [s
25b70 71 6c 69 74 65 33 5f 72 65 73 65 74 7c 72 65 73  qlite3_reset|res
25b80 65 74 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  et], the [sqlite
25b90 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
25ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 6f  .**           ro
25bb0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
25bc0 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ro..*/.int sqlit
25bd0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
25be0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25bf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25c00 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
25c10 20 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32   Datatypes {F102
25c20 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  65}.** KEYWORDS:
25c30 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
25c40 2a 2a 20 7b 46 31 30 32 36 36 7d 45 76 65 72 79  ** {F10266}Every
25c50 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
25c60 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
25c70 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
25c80 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
25c90 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
25ca0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
25cb0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
25cc0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
25cd0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
25ce0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
25cf0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
25d00 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
25d10 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
25d20 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
25d30 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
25d40 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
25d50 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
25d60 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
25d70 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
25d80 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
25d90 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
25da0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
25db0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
25dc0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
25dd0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
25de0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
25df0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
25e00 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
25e10 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
25e20 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
25e30 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
25e40 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
25e50 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
25e60 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
25e70 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
25e80 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
25e90 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
25ea0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
25eb0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
25ec0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
25ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
25ee0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
25ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
25f00 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
25f10 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
25f20 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  ts Values From A
25f30 20 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a   Query {F13800}.
25f40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
25f50 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
25f60 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
25f70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
25f80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25f90 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
25fa0 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73  ion about.** a s
25fb0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
25fc0 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
25fd0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
25fe0 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20  y.  In every.** 
25ff0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
26000 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
26010 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  nter to the .** 
26020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26030 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
26040 6e 67 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  ng.** evaluated 
26050 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
26060 6d 74 2a 5d 20 74 68 61 74 20 77 61 73 20 72 65  mt*] that was re
26070 74 75 72 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  turned from .** 
26080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26090 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
260a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 61   its variants) a
260b0 6e 64 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  nd.** the second
260c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
260d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
260e0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
260f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 0a 2a 2a 20 73  nformation .** s
26100 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
26110 64 2e 20 20 54 68 65 20 6c 65 66 74 2d 6d 6f 73  d.  The left-mos
26120 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
26130 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 68 61  result set.** ha
26140 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 30 2e  s an index of 0.
26150 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
26160 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  L statement is n
26170 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
26180 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
26190 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
261a0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  the column index
261b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
261c0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
261d0 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 20 54  undefined. .** T
261e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
261f0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
26200 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
26210 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
26220 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26230 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
26240 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
26250 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
26260 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
26270 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26280 7a 65 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ze()] has been c
26290 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 6c 79  all subsequently
262a0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
262b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
262c0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
262d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
262e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
262f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
26300 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
26310 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
26320 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
26330 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
26340 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
26350 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
26360 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
26370 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
26380 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26390 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
263a0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
263b0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
263c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
263d0 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
263e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
263f0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
26400 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
26410 6e 64 65 66 69 6e 65 64 2e 20 20 0a 2a 2a 0a 2a  ndefined.  .**.*
26420 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
26430 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
26440 69 6e 65 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  ine returns .** 
26450 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
26460 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
26470 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
26480 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
26490 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
264a0 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  mn.  The returne
264b0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
264c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
264d0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
264e0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
264f0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
26500 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
26510 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
26520 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
26530 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26540 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
26550 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
26560 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
26570 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
26580 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
26590 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
265a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
265b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
265c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
265d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
265e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
265f0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
26600 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
26610 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
26620 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
26630 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
26640 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
26650 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
26660 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
26670 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
26680 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
26690 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
266a0 6e 5f 62 79 74 65 73 28 29 20 0a 2a 2a 20 72 6f  n_bytes() .** ro
266b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
266c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
266d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
266e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20  r string..** If 
266f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
26700 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
26710 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
26720 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
26730 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
26740 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
26750 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
26760 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
26770 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
26780 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
26790 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
267a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
267b0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
267c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
267d0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
267e0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
267f0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
26800 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
26810 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
26820 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20   string..** The 
26830 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
26840 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
26850 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
26860 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
26870 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
26880 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74    For clarity: t
26890 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
268a0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
268b0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
268c0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
268d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
268e0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53  racters..**.** S
268f0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
26900 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
26910 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
26920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26930 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
26940 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
26950 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
26960 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
26970 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
26980 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
26990 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
269a0 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20  ero-length blob 
269b0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
269c0 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
269d0 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
269e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
269f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
26a00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
26a10 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
26a20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
26a30 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
26a40 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
26a50 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
26a60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
26a70 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
26a80 2d 38 2e 20 20 0a 2a 2a 20 54 68 65 20 7a 65 72  -8.  .** The zer
26a90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
26aa0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
26ab0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
26ac0 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
26ad0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
26ae0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
26af0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
26b00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26b10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
26b20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
26b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26b40 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
26b50 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
26b60 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
26b70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26b80 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
26b90 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
26ba0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26bb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
26bc0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
26bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
26be0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
26bf0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
26c00 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
26c10 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
26c20 6c 69 6b 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  like .** [sqlite
26c30 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
26c40 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
26c50 65 78 74 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  ext()], or [sqli
26c60 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
26c70 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
26c80 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
26c90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
26ca0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
26cb0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
26cc0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
26cd0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
26ce0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
26cf0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
26d00 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
26d10 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
26d20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
26d30 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
26d40 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
26d50 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
26d60 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72  to do the conver
26d70 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  sion.** automati
26d80 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
26d90 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
26da0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
26db0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ons that.** are 
26dc0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
26dd0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
26de0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
26df0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
26e00 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
26e10 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
26e20 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
26e30 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
26e40 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
26e50 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
26e60 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
26e70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
26e80 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
26e90 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
26ea0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
26eb0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
26ec0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
26ed0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
26ee0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
26ef0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
26f00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
26f10 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
26f20 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
26f30 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
26f40 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
26f50 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
26f60 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
26f70 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
26f80 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
26f90 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
26fa0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
26fb0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
26fc0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
26fd0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
26fe0 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45  me as for INTEGE
26ff0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
27000 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
27010 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
27020 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
27030 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
27040 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
27050 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
27060 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
27070 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
27080 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
27090 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
270a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
270b0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
270c0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
270d0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
270e0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
270f0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
27100 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
27110 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
27120 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
27130 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
27140 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
27150 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
27160 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
27170 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
27180 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
27190 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
271a0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
271b0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
271c0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
271d0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
271e0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
271f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
27200 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
27210 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
27220 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
27230 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
27240 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
27250 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
27260 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
27270 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
27280 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
27290 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
272a0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
272b0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
272c0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
272d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
272e0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
272f0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
27300 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
27310 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
27320 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
27330 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
27340 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
27350 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
27360 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
27370 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
27380 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
27390 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
273a0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
273b0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
273c0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
273d0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
273e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
273f0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
27400 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
27410 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
27420 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
27430 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
27440 20 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72   .** Type conver
27450 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
27460 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
27470 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
27480 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
27490 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
274a0 3e 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68  >.** <li><p>  Th
274b0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
274c0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
274d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
274e0 65 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ext() .**       
274f0 20 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f     or sqlite3_co
27500 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
27510 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
27520 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
27530 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65  t.**          ne
27540 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
27550 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70  o the string.</p
27560 3e 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ></li>.**.** <li
27570 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61  ><p>  The initia
27580 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
27590 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
275a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
275b0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
275c0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
275d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
275e0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
275f0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
27600 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  erted.**        
27610 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e    to UTF-16.</p>
27620 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
27630 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
27640 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
27650 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
27660 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27670 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  () or.**        
27680 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
27690 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
276a0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
276b0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
276c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  d.**          to
276d0 20 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e   UTF-8.</p></li>
276e0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
276f0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
27700 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
27710 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
27720 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
27730 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
27740 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
27750 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
27760 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
27770 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27780 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
27790 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
277a0 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
277b0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
277c0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
277d0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
277e0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
277f0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
27800 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
27810 6d 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20  metime it is.** 
27820 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
27830 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
27840 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
27850 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  re invalidated. 
27860 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65   .**.** The safe
27870 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
27880 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
27890 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
278a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
278b0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
278c0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
278d0 2a 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  *.**  <ul>.**  <
278e0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
278f0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
27900 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
27910 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
27920 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
27930 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
27940 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
27950 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27960 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
27970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27980 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
27990 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
279a0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
279b0 0a 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  .**  </ul>.**.**
279c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
279d0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
279e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
279f0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
27a00 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a  column_blob(),.*
27a10 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
27a20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
27a30 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
27a40 72 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20  result into the 
27a50 64 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61  desired.** forma
27a60 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
27a70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27a80 74 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33  tes() or sqlite3
27a90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
27aa0 29 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65  ) to.** find the
27ab0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
27ac0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
27ad0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
27ae0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
27af0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
27b00 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
27b10 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
27b20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
27b30 29 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a  ).  And do not.*
27b40 2a 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  * mix calls to s
27b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27b60 78 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c  xt16() with call
27b70 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
27b80 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
27b90 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
27ba0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
27bb0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
27bc0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
27bd0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
27be0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
27bf0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
27c00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
27c10 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
27c20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27c30 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
27c40 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
27c50 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
27c60 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62  ings.** and blob
27c70 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
27c80 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
27c90 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
27ca0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
27cb0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
27cc0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
27cd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27ce0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
27cf0 74 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  to .** [sqlite3_
27d00 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  free()]..**.** I
27d10 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
27d20 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
27d30 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
27d40 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
27d50 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
27d60 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
27d70 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
27d80 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
27d90 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
27da0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
27db0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
27dc0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
27dd0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
27de0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
27df0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
27e00 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
27e10 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
27e20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
27e30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
27e40 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20  .**.** {F13803} 
27e50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27e60 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69  umn_blob(S,N)] i
27e70 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
27e80 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
27e90 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
27ea0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
27eb0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
27ec0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
27ed0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
27ee0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
27ef0 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72 65  blob and then re
27f00 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
27f10 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74      pointer to t
27f20 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
27f30 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30  ue..**.** {F1380
27f40 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
27f50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e  column_bytes(S,N
27f60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27f70 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
27f80 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
27f90 79 74 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62  ytes in the blob
27fa0 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
27fb0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
27fc0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
27fd0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
27fe0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
27ff0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
28000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
28010 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
28020 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28030 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _blob(S,N)] or.*
28040 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
28050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28060 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  S,N)]..**.** {F1
28070 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3809} The [sqlit
28080 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
28090 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
280a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
280b0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
280c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
280d0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
280e0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
280f0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
28100 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
28110 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
28120 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
28130 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
28140 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
28150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28160 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  xt16(S,N)]..**.*
28170 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20 5b  * {F13812} The [
28180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28190 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65  ouble(S,N)] inte
281a0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
281b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
281c0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
281d0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
281e0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
281f0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
28200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28210 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f  nt] S into a flo
28220 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
28230 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
28240 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
28250 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a   of that value..
28260 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54  **.** {F13815} T
28270 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28280 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74  mn_int(S,N)] int
28290 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
282a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
282b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
282c0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
282d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
282e0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
282f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28300 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
28310 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
28320 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
28330 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
28340 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
28350 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
28360 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d 20 54 68  *.** {F13818} Th
28370 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28380 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e  n_int64(S,N)] in
28390 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
283a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
283b0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
283c0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
283d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
283e0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
283f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28400 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
28410 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
28420 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
28430 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
28440 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65  opy of that inte
28450 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ger..**.** {F138
28460 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
28470 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
28480 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28490 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
284a0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
284b0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
284c0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
284d0 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
284e0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
284f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
28500 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28510 74 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20  ted UTF-8 .**   
28520 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
28530 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28540 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
28550 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  ng..**.** {F1382
28560 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
28570 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c  column_text16(S,
28580 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
28590 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
285a0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
285b0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
285c0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
285d0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
285e0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
285f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
28600 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28610 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
28620 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
28630 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
28640 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
28650 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
28660 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28670 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
28680 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d  ..**.** {F13827}
28690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
286a0 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20  lumn_type(S,N)] 
286b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
286c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  s.**          on
286d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
286e0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  L], [SQLITE_INTE
286f0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
28700 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OAT],.**        
28710 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c    [SQLITE_TEXT],
28720 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42   or [SQLITE_BLOB
28730 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
28740 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
28750 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
28760 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
28770 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28780 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
28790 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
287a0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
287b0 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68 65 20  ** {F13830} The 
287c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
287d0 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65  value(S,N)] inte
287e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a  rface returns a.
287f0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
28800 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f  ter to an [unpro
28810 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28820 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
28830 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28840 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
28850 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
28860 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28870 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
28880 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28890 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73  ment] S..*/.cons
288a0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
288b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
288c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
288d0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
288e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
288f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28900 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
28910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28920 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
28930 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
28940 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
28950 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
28960 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28970 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
28980 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
28990 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
289a0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
289b0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
289c0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
289d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
289e0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
289f0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
28a00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
28a10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
28a20 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
28a30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28a40 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
28a50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28a60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
28a70 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
28a80 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
28a90 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
28aa0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
28ab0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
28ac0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28ad0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28ae0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
28af0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
28b00 4f 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a  Object {F13300}.
28b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28b20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
28b30 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
28b40 74 6f 20 64 65 6c 65 74 65 20 61 20 0a 2a 2a 20  to delete a .** 
28b50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28b60 65 6e 74 5d 2e 20 49 66 20 74 68 65 20 73 74 61  ent]. If the sta
28b70 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 65 78  tement was.** ex
28b80 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
28b90 6c 6c 79 2c 20 6f 72 20 6e 6f 74 20 65 78 65 63  lly, or not exec
28ba0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
28bb0 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  n SQLITE_OK is r
28bc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 65  eturned..** If e
28bd0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
28be0 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
28bf0 20 74 68 65 6e 20 61 6e 20 0a 2a 2a 20 5b 65 72   then an .** [er
28c00 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
28c10 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
28c20 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  e].** is returne
28c30 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  d. .**.** This r
28c40 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
28c50 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
28c60 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
28c70 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
28c80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28c90 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76  ment].  If the v
28ca0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
28cb0 61 73 20 6e 6f 74 20 0a 2a 2a 20 63 6f 6d 70 6c  as not .** compl
28cc0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
28cd0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
28ce0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
28cf0 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
28d00 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
28d10 72 20 6f 72 20 61 6e 20 69 6e 74 65 72 72 75 70  r or an interrup
28d20 74 2e 20 20 28 53 65 65 20 5b 73 71 6c 69 74 65  t.  (See [sqlite
28d30 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 2e 29  3_interrupt()].)
28d40 20 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20   .** Incomplete 
28d50 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
28d60 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
28d70 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
28d80 65 6c 65 64 2c 20 20 0a 2a 2a 20 64 65 70 65 6e  eled,  .** depen
28d90 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
28da0 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
28db0 68 65 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  he .** [error co
28dc0 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c  de] returned wil
28dd0 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f  l be [SQLITE_ABO
28de0 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  RT]..**.** INVAR
28df0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
28e00 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1302} The [sqlit
28e10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
28e20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f  interface destro
28e30 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ys the.**       
28e40 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
28e50 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65  tement] S and re
28e60 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20  leases all.**   
28e70 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e         memory an
28e80 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73  d file resources
28e90 20 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62   held by that ob
28ea0 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ject..**.** {F11
28eb0 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  304} If the most
28ec0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
28ed0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28ee0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ] for the.**    
28ef0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
28f00 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
28f10 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a  urned an error,.
28f20 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
28f30 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28f40 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74  ze(S)] returns t
28f50 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a  hat same error..
28f60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
28f70 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
28f80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28f90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28fa0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
28fb0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
28fc0 20 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F13330}.**.** 
28fd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
28fe0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
28ff0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
29000 61 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  a .** [prepared 
29010 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
29020 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74  t..** back to it
29030 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
29040 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
29050 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
29060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
29070 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
29080 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
29090 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
290a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
290b0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
290c0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
290d0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
290e0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
290f0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
29100 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
29110 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
29120 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20  ** {F11332} The 
29130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29140 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
29150 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
29160 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
29170 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20  *          back 
29180 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
29190 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
291a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20  .**.** {F11334} 
291b0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
291c0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
291d0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
291e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70   .**          [p
291f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29200 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
29210 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
29220 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
29230 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b           or if [
29240 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
29250 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
29260 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
29270 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
29280 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
29290 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
292a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
292b0 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49 66 20 74  ** {F11336} If t
292c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
292d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
292e0 73 74 65 70 28 53 29 5d 20 66 6f 72 0a 2a 2a 20  step(S)] for.** 
292f0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
29300 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29310 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
29320 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  or, then.**     
29330 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
29340 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
29350 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
29360 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
29370 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65 20  ** {F11338} The 
29380 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29390 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
293a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
293b0 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
293c0 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69      of any [sqli
293d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
293e0 6e 64 69 6e 67 73 5d 20 6f 6e 20 5b 70 72 65 70  ndings] on [prep
293f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29400 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
29410 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
29420 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
29430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
29440 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
29450 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20  e SQL Functions 
29460 7b 46 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F16100}.** KEYW
29470 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
29480 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
29490 73 7d 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  s} .**.** These 
294a0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
294b0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
294c0 6e 20 61 73 0a 2a 2a 20 22 66 75 6e 63 74 69 6f  n as.** "functio
294d0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
294e0 6e 65 73 22 29 20 61 72 65 20 75 73 65 64 20 74  nes") are used t
294f0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
29500 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
29510 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66  s.** or to redef
29520 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
29530 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
29540 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
29550 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a  gregates.  The.*
29560 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c  * difference onl
29570 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77  y between the tw
29580 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
29590 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
295a0 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  the.** name of t
295b0 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
295c0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
295d0 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
295e0 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
295f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29600 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
29610 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  16 for sqlite3_c
29620 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29630 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
29640 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
29650 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
29660 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
29670 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
29680 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
29690 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
296a0 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  ngle.** program 
296b0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
296c0 6e 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ne [database con
296d0 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 65 72 6e 61  nection] interna
296e0 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 0a 2a 2a  lly, then SQL.**
296f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
29700 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
29710 75 61 6c 6c 79 20 74 6f 20 65 61 63 68 20 5b 64  ually to each [d
29720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29730 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  on]..**.** The s
29740 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
29750 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
29760 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
29770 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a 2a  to be created.**
29780 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a 2a   or redefined..*
29790 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * The length of 
297a0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
297b0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
297c0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
297d0 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72 6d  he .** zero-term
297e0 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
297f0 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
29800 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
29810 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
29820 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
29830 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
29840 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
29850 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
29860 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
29870 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  an SQLITE_ERROR 
29880 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
29890 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
298a0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
298b0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
298c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
298d0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
298e0 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
298f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
29900 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
29910 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
29920 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
29930 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
29940 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
29950 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
29960 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
29970 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
29980 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  what .** [SQLITE
29990 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
299a0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
299b0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
299c0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
299d0 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
299e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
299f0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
29a00 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
29a10 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
29a20 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
29a30 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
29a40 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
29a50 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
29a60 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
29a70 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
29a80 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
29a90 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
29aa0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
29ab0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29ac0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
29ad0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
29ae0 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
29af0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
29b00 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
29b10 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
29b20 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
29b30 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
29b40 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
29b50 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
29b60 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
29b70 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
29b80 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
29b90 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
29ba0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
29bb0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
29bc0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
29bd0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
29be0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
29bf0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
29c00 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20 74  t care what.** t
29c10 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
29c20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
29c30 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
29c40 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51 4c  hould be.** [SQL
29c50 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
29c60 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
29c70 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
29c80 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
29c90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29ca0 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63 74  .** of the funct
29cb0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
29cc0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
29cd0 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ter using.** [sq
29ce0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
29cf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
29d00 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
29d10 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
29d20 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
29d30 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
29d40 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
29d50 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
29d60 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
29d70 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ent the SQL.** f
29d80 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
29d90 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
29da0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
29db0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
29dc0 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  tation of.** the
29dd0 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b 20   xFunc callback 
29de0 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
29df0 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
29e00 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
29e10 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
29e20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
29e30 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
29e40 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
29e50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
29e60 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e 64  .** of xStep and
29e70 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
29e80 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
29e90 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
29ea0 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78 69  delete an.** exi
29eb0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
29ec0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
29ed0 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
29ee0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
29ef0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
29f00 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d  **.** It is perm
29f10 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
29f20 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
29f30 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
29f40 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
29f50 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
29f60 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
29f70 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
29f80 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
29f90 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
29fa0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
29fb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
29fc0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
29fd0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
29fe0 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73  tation most clos
29ff0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2a000 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2a010 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2a020 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
2a030 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2a040 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65 20 5b  * {F16103} The [
2a050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a060 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74  unction16()] int
2a070 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20 65  erface behaves e
2a080 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  xactly.**       
2a090 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33     like [sqlite3
2a0a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a0b0 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79  ()] in every way
2a0c0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a   except that it.
2a0d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2a0e0 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63  rprets the zFunc
2a0f0 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e  tionName argumen
2a100 74 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t as.**         
2a110 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2a120 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2a130 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
2a140 64 20 6f 66 20 61 73 20 61 0a 2a 2a 20 20 20 20  d of as a.**    
2a150 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
2a160 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2a170 2a 2a 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75  ** {F16106} A su
2a180 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2a190 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2a1a0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2a1b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a1c0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2a1d0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2a1e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
2a1f0 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2a200 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2a210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2a220 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
2a230 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c      used to impl
2a240 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2a250 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77  nction named X w
2a260 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73  ith N parameters
2a270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2a280 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 72   having a prefer
2a290 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2a2a0 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46  g of E..**.** {F
2a2b0 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73  16109} A success
2a2c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2a2d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a2e0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2a2f0 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2a300 20 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20     replaces the 
2a310 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76  P, F, S, and L v
2a320 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70  alues from any p
2a330 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a  rior calls with.
2a340 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a350 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e  same D, X, N, an
2a360 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  d E values..**.*
2a370 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65 20 5b  * {F16112} The [
2a380 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a390 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
2a3a0 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2a3b0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
2a3c0 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65     a return code
2a3d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2a3e0 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75  R] if the SQL fu
2a3f0 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  nction name X is
2a400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e  .**          lon
2a410 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74  ger than 255 byt
2a420 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  es exclusive of 
2a430 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2a440 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  tor..**.** {F161
2a450 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73  18} Either F mus
2a460 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20  t be NULL and S 
2a470 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
2a480 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20  LL or else F.** 
2a490 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
2a4a0 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2a4b0 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72   are NULL, other
2a4c0 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  wise.**         
2a4d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a4e0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2a4f0 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75  E,P,F,S,L)] retu
2a500 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  rns [SQLITE_ERRO
2a510 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32  R]..**.** {F1612
2a520 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2a530 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a540 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
2a550 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  e fails with an.
2a560 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
2a570 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
2a580 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65  E_BUSY] if there
2a590 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64   exist [prepared
2a5a0 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20   statements].** 
2a5b0 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
2a5c0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2a5d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a5e0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  n] D..**.** {F16
2a5f0 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2a600 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a610 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e  n(D,X,N,...)] in
2a620 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
2a630 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
2a640 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20    error code of 
2a650 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2a660 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73  f parameter N (s
2a670 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75  pecifying the nu
2a680 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
2a690 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
2a6a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a6b0 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72  n being register
2a6c0 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20  ed) is less.**  
2a6d0 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20          than -1 
2a6e0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2a6f0 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31  127..**.** {F161
2a700 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f  27} When N is no
2a710 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  n-negative, the 
2a720 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a730 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2a740 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2a750 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2a760 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  s callbacks to b
2a770 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
2a780 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
2a790 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2a7a0 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
2a7b0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2a7c0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2a7d0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
2a7e0 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
2a7f0 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57 68 65  .** {F16130} Whe
2a800 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
2a810 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2a820 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2a830 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2a840 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2a850 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2a860 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2a870 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2a880 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
2a890 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65  X with any numbe
2a8a0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2a8b0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d 20 57  **.** {F16133} W
2a8c0 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
2a8d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a8e0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2a8f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
2a900 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
2a910 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2a920 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2a930 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20  ion X.**        
2a940 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69    and when one i
2a950 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61  mplementation ha
2a960 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f  s N>=0 and the o
2a970 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a  ther has N=(-1).
2a980 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2a990 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2a9a0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e  ith a non-zero N
2a9b0 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2a9c0 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20 57 68  *.** {F16136} Wh
2a9d0 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
2a9e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a9f0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2aa00 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2aa10 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
2aa20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2aa30 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2aa40 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20  tion X with.**  
2aa50 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2aa60 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2aa70 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20  ents N but with 
2aa80 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20  different.**    
2aa90 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20        encodings 
2aaa0 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c  E, then the impl
2aab0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65  ementation where
2aac0 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a   E matches the.*
2aad0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
2aae0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2aaf0 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
2ab00 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20 61 6e   {F16139} For an
2ab10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2ab20 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20  unction created 
2ab30 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
2ab40 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2ab50 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2ab60 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65  ,E,P,0,S,L)] the
2ab70 20 66 69 6e 69 61 6c 69 7a 65 72 0a 2a 2a 20 20   finializer.**  
2ab80 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
2ab90 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62   L will always b
2aba0 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c  e invoked exactl
2abb0 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a  y once if the.**
2abc0 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66            step f
2abd0 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c  unction S is cal
2abe0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2abf0 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  times..**.** {F1
2ac00 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74  6142} When SQLit
2ac10 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72  e invokes either
2ac20 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53   the xFunc or xS
2ac30 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a  tep function of.
2ac40 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61  **          an a
2ac50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ac60 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2ac70 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65  or aggregate cre
2ac80 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2ac90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   by [sqlite3_cre
2aca0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2acb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2acc0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2acd0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
2ace0 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20  en the array of 
2acf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2ad00 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61  objects passed a
2ad10 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2ad20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65    third paramete
2ad30 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72  r are always [pr
2ad40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ad50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2ad60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2ad70 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2ad80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2ad90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2ada0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2adb0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2adc0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2add0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2ade0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2adf0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2ae00 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2ae10 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2ae20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2ae30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2ae40 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2ae50 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2ae60 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2ae70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ae80 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2ae90 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2aea0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2aeb0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2aec0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2aed0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2aee0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2aef0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2af00 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2af10 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2af20 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2af30 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2af40 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2af50 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2af60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2af70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2af80 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
2af90 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a 2a  gs {F10267}.**.*
2afa0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2afb0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2afc0 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2afd0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2afe0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2aff0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2b000 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2b010 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2b020 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2b030 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2b040 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2b050 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2b060 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2b070 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2b080 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2b090 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2b0a0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2b0b0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2b0c0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2b0d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b0e0 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2b0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2b100 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2b110 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2b120 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2b130 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2b140 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65  PI3REF: Obsolete
2b150 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
2b160 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2b170 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73   are all now obs
2b180 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72  olete.  In order
2b190 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
2b1a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2b1b0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
2b1c0 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74  er code, we cont
2b1d0 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a  inue to support.
2b1e0 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
2b1f0 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ns.  However, ne
2b200 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72  w development pr
2b210 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76  ojects should av
2b220 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
2b230 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2b240 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
2b250 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
2b260 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
2b270 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
2b280 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
2b290 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e   to tell you wan
2b2a0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e  t they do..*/.in
2b2b0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
2b2c0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
2b2d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74  3_context*);.int
2b2e0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
2b2f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
2b310 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
2b320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
2b330 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
2b340 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2b350 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2b360 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2b370 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2b380 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
2b390 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2b3a0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2b3b0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
2b3c0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2b3d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b3e0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
2b3f0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
2b400 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31 35  eter Values {F15
2b410 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  100}.**.** The C
2b420 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2b430 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2b440 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2b450 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2b460 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2b470 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2b480 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2b490 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2b4a0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2b4b0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2b4c0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2b4d0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2b4e0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2b4f0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2b500 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2b510 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2b520 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2b530 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2b540 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2b550 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2b560 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2b570 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2b580 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2b590 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
2b5a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2b5b0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2b5c0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2b5d0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2b5e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b5f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2b600 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2b610 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b620 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2b630 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2b640 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2b650 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2b660 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2b670 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2b680 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2b690 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2b6a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2b6b0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2b6c0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2b6d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b6e0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2b6f0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2b700 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2b710 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2b720 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2b730 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2b740 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2b750 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
2b760 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2b770 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2b780 72 65 73 70 6f 6e 64 69 6e 67 20 0a 2a 2a 20 5b  responding .** [
2b790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b7a0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  lob | sqlite3_co
2b7b0 6c 75 6d 6e 5f 2a 20 72 6f 75 74 69 6e 65 73 5d  lumn_* routines]
2b7c0 20 65 78 63 65 70 74 20 74 68 61 74 20 0a 2a 2a   except that .**
2b7d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2b7e0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2b7f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b800 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 70  _value] object p
2b810 6f 69 6e 74 65 72 0a 2a 2a 20 69 6e 73 74 65 61  ointer.** instea
2b820 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2b830 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2b840 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2b850 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2b860 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2b870 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2b880 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2b890 20 61 20 55 54 46 31 36 20 73 74 72 69 6e 67 0a   a UTF16 string.
2b8a0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
2b8b0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
2b8c0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
2b8d0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
2b8e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2b8f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
2b900 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
2b910 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
2b920 72 61 63 74 20 55 54 46 31 36 20 73 74 72 69 6e  ract UTF16 strin
2b930 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
2b940 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
2b950 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2b960 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2b970 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2b980 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2b990 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2b9a0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2b9b0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2b9c0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2b9d0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2b9e0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2b9f0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2ba00 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2ba10 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2ba20 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2ba30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2ba40 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2ba50 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2ba60 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2ba70 20 77 6f 72 64 73 20 69 66 20 74 68 65 20 76 61   words if the va
2ba80 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
2ba90 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
2baa0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
2bab0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
2bac0 20 69 73 20 64 6f 6e 65 2e 20 20 4f 74 68 65 72   is done.  Other
2bad0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2bae0 6f 6e 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  on occurs.  The 
2baf0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2bb00 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2bb10 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2bb20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2bb30 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2bb40 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2bb50 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2bb60 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2bb70 20 74 68 61 74 0a 2a 2a 20 69 73 20 72 65 74 75   that.** is retu
2bb80 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2bb90 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
2bba0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2bbb0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
2bbc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2bbd0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
2bbe0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
2bbf0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2bc00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2bc10 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2bc20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2bc30 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
2bc40 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2bc50 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2bc60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2bc70 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].  .**.** These
2bc80 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2bc90 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2bca0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
2bcb0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2bcc0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
2bcd0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
2bce0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
2bcf0 72 73 2e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56  rs..**.**.** INV
2bd00 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2bd10 46 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  F15103} The [sql
2bd20 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2bd30 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2bd40 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2bd50 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2bd60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2bd70 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2bd80 20 62 6c 6f 62 20 61 6e 64 20 74 68 65 6e 20 72   blob and then r
2bd90 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
2bda0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
2bdb0 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
2bdc0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  lue..**.** {F151
2bdd0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
2bde0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d  _value_bytes(V)]
2bdf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2be00 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2be10 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2be20 65 73 20 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f  es in the blob o
2be30 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
2be40 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2be50 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2be60 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2be70 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2be80 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2be90 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2bea0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2beb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2bec0 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ob(V)] or.**    
2bed0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
2bee0 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a  alue_text(V)]..*
2bef0 2a 0a 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68  *.** {F15109} Th
2bf00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2bf10 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74  _bytes16(V)] int
2bf20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2bf30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2bf40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2bf50 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
2bf60 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2bf70 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2bf80 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2bf90 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2bfa0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2bfb0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2bfc0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2bfd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
2bfe0 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a  e_text16(V)],.**
2bff0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c000 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2c010 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  e(V)], or [sqlit
2c020 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2c030 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  e(V)]..**.** {F1
2c040 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  5112} The [sqlit
2c050 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2c060 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2c070 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c080 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2c090 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c0a0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2c0b0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2c0c0 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
2c0d0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2c0e0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
2c0f0 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31  ue..**.** {F1511
2c100 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2c110 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e  value_int(V)] in
2c120 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c130 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c140 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2c150 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c160 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
2c170 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2c180 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2c190 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
2c1a0 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
2c1b0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2c1c0 2a 20 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b  * {F15118} The [
2c1d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2c1e0 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
2c1f0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c200 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c210 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c220 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c230 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2c240 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2c250 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2c260 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
2c270 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
2c280 20 7b 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {F15121} The [s
2c290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c2a0 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
2c2b0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c2c0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c2d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c2e0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c2f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2c300 65 64 20 55 54 46 2d 38 20 0a 2a 2a 20 20 20 20  ed UTF-8 .**    
2c310 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2c320 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c330 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2c340 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34  g..**.** {F15124
2c350 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c360 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20  alue_text16(V)] 
2c370 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2c380 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2c390 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2c3a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c3b0 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
2c3c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2c3d0 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2c3e0 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e  aligned UTF-16 n
2c3f0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2c400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
2c410 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
2c420 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2c430 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2c440 7b 46 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71  {F15127} The [sq
2c450 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c460 31 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61  16be(V)] interfa
2c470 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c480 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2c490 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c4a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2c4b0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2c4c0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2c4d0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2c4e0 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
2c4f0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2c500 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2c510 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c520 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2c530 2a 20 7b 46 31 35 31 33 30 7d 20 54 68 65 20 5b  * {F15130} The [
2c540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c550 78 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72  xt16le(V)] inter
2c560 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c570 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c580 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c590 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c5a0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2c5b0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2c5c0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2c5d0 65 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ed UTF-16 little
2c5e0 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
2c5f0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2c600 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c610 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2c620 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20  .**.** {F15133} 
2c630 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2c640 75 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65  ue_type(V)] inte
2c650 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2c660 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66            one of
2c670 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20   [SQLITE_NULL], 
2c680 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2c690 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
2c6a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2c6b0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20  QLITE_TEXT], or 
2c6c0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
2c6d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
2c6e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2c6f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2c700 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
2c710 20 7b 46 31 35 31 33 36 7d 20 54 68 65 20 5b 73   {F15136} The [s
2c720 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2c730 65 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e  eric_type(V)] in
2c740 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2c760 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2c770 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c780 74 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20  t V into either 
2c790 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a  an integer or.**
2c7a0 20 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61            a floa
2c7b0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2c7c0 20 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f   if it can do so
2c7d0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
2c7e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66  .**          inf
2c7f0 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65  ormation, and re
2c800 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51  turns one of [SQ
2c810 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20  LITE_NULL],.**  
2c820 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2c830 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2c840 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2c850 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20  E_TEXT], or.**  
2c860 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2c870 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2c880 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
2c890 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63       the [protec
2c8a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c8b0 65 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65  e] object V afte
2c8c0 72 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  r the conversion
2c8d0 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e   attempt..*/.con
2c8e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c8f0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2c900 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2c910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2c920 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2c930 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2c940 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2c950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2c960 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2c970 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2c980 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2c990 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2c9a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2c9b0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2c9c0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2c9d0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2c9e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2c9f0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2ca00 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2ca10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ca20 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ca30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ca40 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2ca50 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ca60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ca70 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2ca80 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2ca90 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2caa0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2cab0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2cac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2cad0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2cae0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2caf0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2cb00 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2cb10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cb20 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2cb30 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2cb40 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a  ntext {F16210}.*
2cb50 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
2cb60 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
2cb70 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2cb80 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
2cb90 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
2cba0 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
2cbb0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
2cbc0 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 54 68 65   state.  .** The
2cbd0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
2cbe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2cbf0 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
2cc00 69 6e 65 20 69 73 0a 2a 2a 20 69 73 20 63 61 6c  ine is.** is cal
2cc10 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69 63  led for a partic
2cc20 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20  ular aggregate, 
2cc30 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73  SQLite allocates
2cc40 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72   nBytes of memor
2cc50 79 0a 2a 2a 20 7a 65 72 6f 73 20 74 68 61 74 20  y.** zeros that 
2cc60 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2cc70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2cc80 20 69 74 2e 0a 2a 2a 20 4f 6e 20 73 65 63 6f 6e   it..** On secon
2cc90 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2cca0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2ccb0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ccc0 65 78 74 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ext().** for the
2ccd0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2cce0 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 20  function index, 
2ccf0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2cd00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2cd10 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2cd20 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67  on.** of the agg
2cd30 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74  regate can use t
2cd40 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
2cd50 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
2cd60 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
2cd70 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2cd80 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
2cd90 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
2cda0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
2cdb0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
2cdc0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2cdd0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
2cde0 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
2cdf0 66 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  f the .** [sqlit
2ce00 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
2ce10 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
2ce20 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
2ce30 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
2ce40 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
2ce50 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
2ce60 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
2ce70 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
2ce80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2ce90 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2cea0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2ceb0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2cec0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2ced0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2cee0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2cef0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2cf00 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20  .**.** {F16211} 
2cf10 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
2cf20 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2cf30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2cf40 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
2cf50 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
2cf60 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
2cf70 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
2cf80 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
2cf90 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
2cfa0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
2cfb0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2cfc0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 4e 20 62  o allocation N b
2cfd0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a  ytes of memory,.
2cfe0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2cff0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
2d000 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
2d010 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61  er to the alloca
2d020 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2d030 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  memory..**.** {F
2d040 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
2d050 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2d060 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2d070 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2d080 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d090 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
2d0a0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2d0b0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
2d0c0 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {F16215} Secon
2d0d0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2d0e0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
2d0f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2d100 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d110 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
2d120 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
2d130 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
2d140 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
2d150 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
2d160 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
2d170 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
2d180 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
2d190 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
2d1a0 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
2d1b0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
2d1c0 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54 68 65  .** {F16217} The
2d1d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2d1e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
2d1f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2d200 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
2d210 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
2d220 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
2d230 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
2d240 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2d250 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2d260 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d270 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
2d280 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d290 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
2d2a0 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
2d2b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
2d2c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
2d2d0 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
2d2e0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
2d2f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
2d300 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2d310 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
2d320 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
2d330 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
2d340 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a  ons {F16240}.**.
2d350 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
2d360 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
2d370 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2d380 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2d390 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
2d3a0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
2d3b0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
2d3c0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2d3d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2d3e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2d3f0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2d400 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d410 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2d420 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2d430 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2d440 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2d450 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
2d460 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
2d470 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2d480 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2d490 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2d4a0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2d4b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d4c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2d4d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
2d4e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2d4f0 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6243} The [sqlit
2d500 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d  e3_user_data(C)]
2d510 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d520 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2d530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70  .**          P p
2d540 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
2d550 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d560 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2d570 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2d580 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2d590 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d5a0 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
2d5b0 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
2d5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2d5d0 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
2d5e0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2d5f0 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20  ted with .**    
2d600 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2d610 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f  ontext] C..*/.vo
2d620 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
2d630 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
2d640 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2d650 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
2d660 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
2d670 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36  r Functions {F16
2d680 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  250}.**.** The s
2d690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2d6a0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
2d6b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2d6c0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2d6d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
2d6e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d6f0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
2d700 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2d710 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d720 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2d730 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2d740 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2d750 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2d760 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2d770 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2d780 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2d790 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2d7a0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2d7b0 2a 2a 20 7b 46 31 36 32 35 33 7d 20 54 68 65 20  ** {F16253} The 
2d7c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2d7d0 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69  _db_handle(C)] i
2d7e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d7f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2d800 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69  *          D poi
2d810 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73  nter from the [s
2d820 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d830 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2d840 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
2d850 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2d860 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d870 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  16(D,X,N,E,P,F,S
2d880 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a  ,L)] call that.*
2d890 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
2d8a0 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75  tered the SQL fu
2d8b0 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
2d8c0 64 20 77 69 74 68 20 0a 2a 2a 20 20 20 20 20 20  d with .**      
2d8d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e      [sqlite3_con
2d8e0 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69  text] C..*/.sqli
2d8f0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2d900 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2d910 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2d920 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d930 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2d940 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31 36 32  liary Data {F162
2d950 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  70}.**.** The fo
2d960 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
2d970 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
2d980 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
2d990 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
2d9a0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 2d 64  associate meta-d
2d9b0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
2d9c0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
2d9d0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
2d9e0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
2d9f0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
2da00 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
2da10 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
2da20 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
2da30 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
2da40 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
2da50 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
2da60 61 2d 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  a-data may be pr
2da70 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
2da80 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
2da90 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
2daa0 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
2dab0 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
2dac0 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
2dad0 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
2dae0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
2daf0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2db00 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
2db10 2a 2a 20 6d 65 74 61 2d 64 61 74 61 20 61 73 73  ** meta-data ass
2db20 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2db30 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65   SQL value passe
2db40 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72  d as the regular
2db50 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70   expression.** p
2db60 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d  attern.  The com
2db70 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78  piled regular ex
2db80 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
2db90 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70  reused on multip
2dba0 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  le.** invocation
2dbb0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2dbc0 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74  nction so that t
2dbd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74  he original patt
2dbe0 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f  ern string.** do
2dbf0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2dc00 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20  e recompiled on 
2dc10 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  each invocation.
2dc20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2dc30 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2dc40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dc50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2dc60 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a  the meta-data.**
2dc70 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
2dc80 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2dc90 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
2dca0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
2dcb0 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
2dcc0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
2dcd0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2dce0 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 6e 6f 20 6d  tion..** If no m
2dcf0 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65  eta-data has bee
2dd00 6e 20 65 76 65 72 20 62 65 65 6e 20 73 65 74 20  n ever been set 
2dd10 66 6f 72 20 74 68 65 20 4e 74 68 0a 2a 2a 20 61  for the Nth.** a
2dd20 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2dd30 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2dd40 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2dd50 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
2dd60 74 65 72 0a 2a 2a 20 68 61 73 20 63 68 61 6e 67  ter.** has chang
2dd70 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2dd80 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 20  a-data was set, 
2dd90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  then sqlite3_get
2dda0 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 72 65  _auxdata().** re
2ddb0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2ddc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
2ddd0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2dde0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2ddf0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 2d 64  saves the meta-d
2de00 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2de10 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2de20 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2de30 74 61 2d 64 61 74 61 20 66 6f 72 20 74 68 65 20  ta-data for the 
2de40 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
2de50 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2de60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2de70 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
2de80 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
2de90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2dea0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
2deb0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2dec0 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2ded0 6e 20 64 65 73 74 72 6f 79 65 64 2e 20 0a 2a 2a  n destroyed. .**
2dee0 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
2def0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2df00 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2df10 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63 74 69  uctor .** functi
2df20 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
2df30 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2df40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2df50 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
2df60 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65 6e 20   meta-data when 
2df70 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2df80 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
2df90 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
2dfa0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
2dfb0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
2dfc0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
2dfd0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
2dfe0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
2dff0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
2e000 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
2e010 20 6d 65 74 61 2d 64 61 74 61 20 6f 6e 0a 2a 2a   meta-data on.**
2e020 20 61 6e 79 20 70 61 72 61 6d 65 74 65 72 20 6f   any parameter o
2e030 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
2e040 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65  t any time.  The
2e050 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 0a   only guarantee.
2e060 2a 2a 20 69 73 20 74 68 61 74 20 74 68 65 20 64  ** is that the d
2e070 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
2e080 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
2e090 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 0a  the metadata is.
2e0a0 2a 2a 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  ** dropped..**.*
2e0b0 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
2e0c0 65 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73  eta-data is pres
2e0d0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
2e0e0 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
2e0f0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
2e100 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
2e110 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
2e120 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
2e130 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
2e140 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61  es and SQL varia
2e150 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  bles..**.** Thes
2e160 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2e170 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2e180 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2e190 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
2e1a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2e1b0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2e1c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2e1d0 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71  {F16272} The [sq
2e1e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e1f0 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  a(C,N)] interfac
2e200 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2e210 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
2e220 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  to metadata asso
2e230 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2e240 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  Nth parameter of
2e250 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e260 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
2e270 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43  ose context is C
2e280 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
2e290 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
2e2a0 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  a associated.** 
2e2b0 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
2e2c0 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  at parameter..**
2e2d0 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54 68 65  .** {F16274} The
2e2e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2e2f0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2e300 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e  interface assign
2e310 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  s a metadata.** 
2e320 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2e330 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61   P to the Nth pa
2e340 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53  rameter of the S
2e350 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  QL function with
2e360 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20   context.**     
2e370 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46       C..**.** {F
2e380 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69  16276} SQLite wi
2e390 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
2e3a0 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
2e3b0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2e3c0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
2e3d0 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64  ich is the metad
2e3e0 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f  ata pointer P fo
2e3f0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
2e400 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
2e410 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2e420 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65  ta(C,N,P,D)] whe
2e430 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20  n SQLite ceases 
2e440 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20  to hold.**      
2e450 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61      the metadata
2e460 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d  ..**.** {F16277}
2e470 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
2e480 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20  o hold metadata 
2e490 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  for an SQL funct
2e4a0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ion parameter.**
2e4b0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74            when t
2e4c0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
2e4d0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2e4e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  es..**.** {F1627
2e4f0 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  8} When [sqlite3
2e500 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
2e510 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ,P,D)] is invoke
2e520 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  d, the destructo
2e530 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  r.**          is
2e540 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20   called for any 
2e550 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61  prior metadata a
2e560 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2e570 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2e590 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d  text C and param
2e5a0 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  eter N..**.** {F
2e5b0 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69  16279} SQLite wi
2e5c0 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74  ll call destruct
2e5d0 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61  ors for any meta
2e5e0 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69  data it is holdi
2e5f0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ng.**          i
2e600 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b  n a particular [
2e610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e620 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65  nt] S when eithe
2e630 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2e640 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e650 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2e660 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
2e670 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  led..*/.void *sq
2e680 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e690 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2e6a0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
2e6b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2e6c0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2e6d0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
2e6e0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
2e6f0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
2e700 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
2e710 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
2e720 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
2e730 65 68 61 76 69 6f 72 20 7b 46 31 30 32 38 30 7d  ehavior {F10280}
2e740 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
2e750 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 66   special value f
2e760 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
2e770 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2e780 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
2e790 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
2e7a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2e7b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2e7c0 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64  ob()].  If the d
2e7d0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
2e7e0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
2e7f0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
2e800 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2e810 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
2e820 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
2e830 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
2e840 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
2e850 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
2e860 64 2e 20 20 54 68 65 20 0a 2a 2a 20 53 51 4c 49  d.  The .** SQLI
2e870 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
2e880 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
2e890 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
2e8a0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
2e8b0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
2e8c0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
2e8d0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
2e8e0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
2e8f0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
2e900 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
2e910 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
2e920 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
2e930 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
2e940 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
2e950 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
2e960 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
2e970 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
2e980 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
2e990 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
2e9a0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
2e9b0 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
2e9c0 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
2e9d0 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2e9e0 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
2e9f0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
2ea00 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
2ea10 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
2ea20 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
2ea30 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
2ea40 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
2ea50 20 46 75 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30   Function {F1640
2ea60 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
2ea70 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2ea80 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
2ea90 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2eaa0 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
2eab0 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
2eac0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2ead0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
2eae0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eaf0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2eb00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eb10 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
2eb20 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2eb30 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2eb40 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
2eb50 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
2eb60 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
2eb70 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2eb80 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 5d 20 66 61  lite3_bind_*] fa
2eb90 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
2eba0 73 20 75 73 65 64 0a 2a 2a 20 74 6f 20 62 69 6e  s used.** to bin
2ebb0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
2ebc0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
2ebd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ebe0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
2ebf0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2ec00 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2ec10 74 65 33 5f 62 69 6e 64 5f 2a 20 64 6f 63 75 6d  te3_bind_* docum
2ec20 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a  entation] for.**
2ec30 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2ec40 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
2ec50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ec60 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
2ec70 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2ec80 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2ec90 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2eca0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2ecb0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
2ecc0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
2ecd0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
2ece0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ecf0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
2ed00 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
2ed10 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
2ed20 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 2a  rd parameter. .*
2ed30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2ed40 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  sult_zeroblob() 
2ed50 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74  interfaces set t
2ed60 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2ed70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ed80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ed90 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f   to be a BLOB co
2eda0 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72  ntaining all zer
2edb0 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e  o.** bytes and N
2edc0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20   bytes in size, 
2edd0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76  where N is the v
2ede0 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20  alue of the 2nd 
2edf0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2ee00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ee10 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
2ee20 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2ee30 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2ee40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
2ee50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2ee60 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
2ee70 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
2ee80 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
2ee90 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2eea0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2eeb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2eec0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2eed0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
2eee0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
2eef0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
2ef00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
2ef10 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
2ef20 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  n..** SQLite use
2ef30 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
2ef40 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
2ef50 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
2ef60 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
2ef70 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
2ef80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2ef90 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
2efa0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
2efb0 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74   message.  SQLit
2efc0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2efd0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2efe0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2eff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f000 6f 72 28 29 20 61 73 20 55 54 46 38 2e 20 53 51  or() as UTF8. SQ
2f010 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2f020 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2f030 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2f040 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2f050 54 46 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  TF16 in native.*
2f060 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
2f070 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2f080 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2f090 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
2f0a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2f0b0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
2f0c0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
2f0d0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
2f0e0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2f0f0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
2f100 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
2f110 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
2f120 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
2f130 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f150 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
2f160 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f170 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
2f180 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2f190 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
2f1a0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
2f1b0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
2f1c0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2f1d0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
2f1e0 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
2f1f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f200 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2f210 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f220 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
2f230 6d 61 6b 65 20 61 20 63 6f 70 79 20 70 72 69 76  make a copy priv
2f240 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2f250 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2f260 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2f270 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2f280 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2f290 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2f2a0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2f2b0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2f2c0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2f2d0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
2f2e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f2f0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
2f300 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
2f310 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
2f320 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
2f330 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
2f340 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
2f350 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
2f360 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
2f370 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
2f380 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
2f390 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2f3a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2f3b0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2f3c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f3d0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
2f3e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
2f3f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
2f400 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f410 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
2f420 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2f430 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74  s SQLite.** to t
2f440 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e  hrow an error in
2f450 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2f460 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
2f470 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20  s to long.** to 
2f480 72 65 70 72 65 73 65 6e 74 2e 20 20 54 68 65 20  represent.  The 
2f490 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2f4a0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
2f4b0 0a 2a 2a 20 63 61 75 73 65 73 20 53 51 4c 69 74  .** causes SQLit
2f4c0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  e to throw an ex
2f4d0 63 65 70 74 69 6f 6e 20 69 6e 64 69 63 61 74 69  ception indicati
2f4e0 6e 67 20 74 68 61 74 20 74 68 65 20 61 0a 2a 2a  ng that the a.**
2f4f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2f500 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
2f510 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f520 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2f530 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2f540 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2f550 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f560 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f570 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2f580 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2f590 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2f5a0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2f5b0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
2f5c0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2f5d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2f5e0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2f5f0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2f600 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f610 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f620 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2f630 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2f640 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2f650 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2f660 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f670 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2f680 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2f690 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2f6a0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f6b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f6c0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2f6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f6e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2f6f0 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2f700 5f 74 65 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73  _text16(), .** s
2f710 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2f720 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2f730 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f740 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2f750 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2f760 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2f770 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f780 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f790 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2f7a0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2f7b0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2f7c0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2f7d0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2f7e0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2f7f0 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2f800 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2f810 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53  spectively..** S
2f820 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
2f830 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
2f840 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f850 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
2f860 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2f870 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f880 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2f890 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  s..** If the 3rd
2f8a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f8b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f8c0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2f8d0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
2f8e0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
2f8f0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
2f900 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2f910 61 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75  ameter .** throu
2f920 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2f930 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2f940 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2f950 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2f960 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2f970 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2f980 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2f990 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
2f9a0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2f9b0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
2f9c0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
2f9d0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2f9e0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
2f9f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2fa00 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
2fa10 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
2fa20 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2fa30 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2fa40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2fa50 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2fa60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fa70 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
2fa80 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
2fa90 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
2faa0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
2fab0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
2fac0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
2fad0 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65 6e  blob result when
2fae0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2faf0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2fb00 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2fb10 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2fb20 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2fb30 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2fb40 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2fb50 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2fb60 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2fb70 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2fb80 54 41 54 49 43 2c 20 74 68 65 6e 0a 2a 2a 20 53  TATIC, then.** S
2fb90 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2fba0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 62  at the text or b
2fbb0 6c 6f 62 20 72 65 73 75 6c 74 20 69 73 20 63 6f  lob result is co
2fbc0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
2fbd0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 63 6f 70  .** does not cop
2fbe0 79 20 74 68 65 20 73 70 61 63 65 20 6f 72 20 63  y the space or c
2fbf0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
2fc00 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
2fc10 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
2fc20 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
2fc30 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2fc40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2fc50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2fc60 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
2fc70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fc80 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
2fc90 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
2fca0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
2fcb0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
2fcc0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2fcd0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
2fce0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
2fcf0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2fd00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
2fd10 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
2fd20 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2fd30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2fd40 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2fd50 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2fd60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2fd70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fd80 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2fd90 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2fda0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2fdb0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2fdc0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2fdd0 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
2fde0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2fdf0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2fe00 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2fe10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2fe20 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2fe30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2fe40 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
2fe50 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
2fe60 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
2fe70 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
2fe80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fe90 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
2fea0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2feb0 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   A [protected sq
2fec0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2fed0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2fee0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2fef0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2ff00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ff10 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2ff20 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2ff30 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2ff40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2ff50 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2ff60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2ff70 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2ff80 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2ff90 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2ffa0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2ffb0 65 61 64 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65  ead .** than the
2ffc0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
2ffd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ffe0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fff0 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
30000 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
30010 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
30020 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
30030 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
30040 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
30050 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65  .** {F16403} The
30060 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20   default return 
30070 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53  value from any S
30080 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  QL function is N
30090 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
300a0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
300b0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
300c0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
300d0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
300e0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
300f0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30100 6e 20 43 20 74 6f 20 62 65 20 61 20 62 6c 6f 62  n C to be a blob
30110 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73   that is N bytes
30120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
30130 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20  length and with 
30140 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20  content pointed 
30150 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  to by V..**.** {
30160 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c  F16409} The [sql
30170 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
30180 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  le(C,V)] interfa
30190 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
301a0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
301b0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
301c0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
301d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
301e0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  alue V..**.** {F
301f0 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16412} The [sqli
30200 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30210 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
30220 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
30230 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
30240 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
30250 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
30260 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
30270 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
30280 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
30290 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 38 20 65  OR] and a UTF8 e
302a0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70  rror message cop
302b0 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
302c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
302d0 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65   first zero byte
302e0 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
302f0 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20  s are read if N 
30300 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a  is positive..**.
30310 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20  ** {F16415} The 
30320 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30330 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20  error16(C,V,N)] 
30340 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30350 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
30360 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
30370 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30380 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
30390 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
303a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
303b0 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
303c0 20 55 54 46 31 36 20 6e 61 74 69 76 65 20 62 79   UTF16 native by
303d0 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
303e0 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
303f0 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
30400 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
30410 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
30420 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
30430 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
30440 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
30450 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
30460 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  F16418} The [sql
30470 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30480 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
30490 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
304a0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
304b0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
304c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
304d0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
304e0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
304f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
30500 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
30510 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
30520 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
30530 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68  *.** {F16421} Th
30540 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30550 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
30560 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30570 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
30580 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
30590 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
305a0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
305b0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
305c0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
305d0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
305e0 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
305f0 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
30600 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34  e..**.** {F16424
30610 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30620 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
30630 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
30640 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
30650 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
30660 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
30670 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
30680 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
30690 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
306a0 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
306b0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
306c0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
306d0 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68  *.** {F16427} Th
306e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
306f0 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
30700 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30710 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
30720 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
30730 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
30740 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
30750 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
30760 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {F16430} The [s
30770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
30780 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
30790 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
307a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
307b0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
307c0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
307d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
307e0 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
307f0 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  F16433} The [sql
30800 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
30810 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
30820 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30830 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30840 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30850 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
30860 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65  .** {F16436} The
30870 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30880 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
30890 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
308a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
308b0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
308c0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
308d0 62 65 20 74 68 65 20 55 54 46 38 20 73 74 72 69  be the UTF8 stri
308e0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 56  ng.**          V
308f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
30900 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
30910 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
30920 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
30930 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
30940 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
30950 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 39  e..**.** {F16439
30960 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30970 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
30980 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
30990 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
309a0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
309b0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
309c0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
309d0 46 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  F16 native byte 
309e0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
309f0 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
30a00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30a10 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
30a20 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20      negative or 
30a30 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
30a40 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
30a50 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
30a60 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68 65 20  ** {F16442} The 
30a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30a80 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
30a90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30aa0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
30ab0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
30ac0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
30ad0 74 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20  to be the UTF16 
30ae0 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
30af0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
30b00 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
30b10 7a 65 72 6f 20 69 66 20 4e 20 69 73 0a 2a 2a 20  zero if N is.** 
30b20 20 20 20 20 20 20 20 20 20 69 73 20 6e 65 67 61           is nega
30b30 74 69 76 65 20 6f 72 20 74 68 65 20 66 69 72 73  tive or the firs
30b40 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
30b50 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
30b60 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
30b70 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
30b80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
30b90 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
30ba0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30bc0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30bd0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
30be0 65 20 55 54 46 31 36 20 6c 69 74 74 6c 65 2d 65  e UTF16 little-e
30bf0 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
30c00 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
30c10 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30c20 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
30c30 20 20 20 20 6e 65 67 61 74 69 76 65 20 6f 72 20      negative or 
30c40 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
30c50 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
30c60 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
30c70 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65 20  ** {F16448} The 
30c80 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30c90 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74 65  value(C,V)] inte
30ca0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30cb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
30cc0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
30cd0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 5b  nction C to be [
30ce0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30cf0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20  te3_value].**   
30d00 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e         object V.
30d10 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20  .**.** {F16451} 
30d20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30d30 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
30d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
30d50 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
30d60 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
30d70 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
30d80 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20  to be an N-byte 
30d90 62 6c 6f 62 20 6f 66 20 61 6c 6c 20 7a 65 72 6f  blob of all zero
30da0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34  s..**.** {F16454
30db0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30dc0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61  esult_error()] a
30dd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
30de0 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a  lt_error16()].**
30df0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
30e00 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79  aces make a copy
30e10 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20   of their error 
30e20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
30e30 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  before.**       
30e40 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a     returning..**
30e50 0a 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20  .** {F16457} If 
30e60 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
30e70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
30e90 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
30ea0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30eb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
30ec0 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
30ed0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30ee0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
30ef0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
30f00 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
30f10 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
30f20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
30f30 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30f40 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
30f50 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53   the constant [S
30f60 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a  QLITE_STATIC].**
30f70 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e            then n
30f80 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  o destructor is 
30f90 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ever called on t
30fa0 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64  he pointer V and
30fb0 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20   SQLite.**      
30fc0 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74      assumes that
30fd0 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e   V is immutable.
30fe0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20  .**.** {F16460} 
30ff0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
31000 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
31010 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31020 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
31030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31040 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31050 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
31060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31070 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
31080 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
31090 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
310a0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
310b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
310c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
310d0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
310e0 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
310f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31100 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
31110 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61  then the interfa
31120 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ces makes a copy
31130 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
31140 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56      content of V
31150 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65   and retains the
31160 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   copy..**.** {F1
31170 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64  6463} If the D d
31180 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
31190 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
311a0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
311b0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
311c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
311d0 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
311e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
311f0 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
31200 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
31210 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31220 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
31230 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
31240 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
31250 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
31260 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76  ,N,D)] is some v
31270 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a  alue other than.
31280 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
31290 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
312a0 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53  E_STATIC] and [S
312b0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
312c0 20 74 68 65 6e 20 0a 2a 2a 20 20 20 20 20 20 20   then .**       
312d0 20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69     SQLite will i
312e0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
312f0 63 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73  ctor D with V as
31300 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65   its only argume
31310 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nt.**          w
31320 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
31330 68 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76  hed with the V v
31340 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  alue..*/.void sq
31350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31360 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
31370 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
31380 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
31390 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
313a0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
313b0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
313c0 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
313d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
313e0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
313f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
31400 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
31410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31420 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
31430 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
31440 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
31450 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31460 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
31470 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31480 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31490 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
314a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
314b0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
314c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
314d0 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
314e0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
314f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31500 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
31510 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
31520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31530 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
31540 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
31550 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
31560 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
31570 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31580 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31590 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
315a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
315b0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
315c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
315d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
315e0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
315f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
31600 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
31610 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31620 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31630 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
31640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31650 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
31660 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
31670 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31680 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
31690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
316a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
316b0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
316c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
316d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
316e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
316f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31700 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31710 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
31720 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
31730 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
31740 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
31750 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
31760 75 65 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a  uences {F16600}.
31770 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
31780 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
31790 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
317a0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
317b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
317c0 2a 5d 20 68 61 6e 64 6c 65 20 73 70 65 63 69 66  *] handle specif
317d0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
317e0 20 61 72 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a   argument. .**.*
317f0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
31800 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
31810 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
31820 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
31830 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
31840 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31850 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
31860 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31870 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
31880 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
31890 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
318a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
318b0 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
318c0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
318d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
318e0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
318f0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
31900 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
31910 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
31920 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
31930 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
31940 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
31950 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
31960 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
31970 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
31980 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
31990 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
319a0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
319b0 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
319c0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
319d0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
319e0 65 2d 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d  e-endian or UTF-
319f0 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65  16 big-endian re
31a00 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68 65 0a  spectively. The.
31a10 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  ** third argumen
31a20 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20  t might also be 
31a30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
31a40 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61  IGNED] to indica
31a50 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72  te that.** the r
31a60 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70  outine expects p
31a70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69  ointers to 16-bi
31a80 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73  t word aligned s
31a90 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46  trings.** of UTF
31aa0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
31ab0 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74   byte order of t
31ac0 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72  he host computer
31ad0 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
31ae0 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
31af0 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
31b00 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
31b10 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
31b20 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69  gument.  If it i
31b30 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
31b40 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
31b50 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
31b60 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
31b70 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
31b80 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
31b90 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20  ymore)..** Each 
31ba0 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
31bb0 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
31bc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
31bd0 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
31be0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
31bf0 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
31c00 0a 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61  .** the fourth a
31c10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
31c20 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31c30 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ion() or.** sqli
31c40 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31c50 74 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20  tion16() as its 
31c60 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
31c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
31c80 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
31c90 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
31ca0 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
31cb0 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
31cc0 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
31cd0 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
31ce0 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
31cf0 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
31d00 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
31d10 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
31d20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
31d30 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
31d40 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
31d50 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
31d60 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61  red. {END} The a
31d70 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
31d80 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75  ed collation rou
31d90 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  tine should.** r
31da0 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20  eturn negative, 
31db0 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65  zero or positive
31dc0 20 69 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   if.** the first
31dd0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
31de0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
31df0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
31e00 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 73 74  the second.** st
31e10 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
31e20 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
31e30 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31e40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31e50 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
31e60 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
31e70 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
31e80 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
31e90 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
31ea0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
31eb0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
31ec0 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
31ed0 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
31ee0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
31ef0 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
31f00 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
31f10 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
31f20 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
31f30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
31f40 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
31f50 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
31f60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
31f70 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
31f80 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
31f90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 79 20 61 72   when.** they ar
31fa0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
31fb0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
31fc0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
31fd0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 0a  ation functions.
31fe0 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ** or when the [
31ff0 73 71 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61  sqlite3*] databa
32000 73 65 20 68 61 6e 64 6c 65 20 69 73 20 63 6c 6f  se handle is clo
32010 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
32020 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
32030 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
32040 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20  *.** {F16603} A 
32050 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
32060 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
32070 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
32080 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32090 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
320a0 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
320b0 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
320c0 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
320d0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
320e0 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
320f0 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
32100 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
32110 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32120 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20  ction] B for.** 
32130 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
32140 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69  es having encodi
32150 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ng E..**.** {F16
32160 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65  604} SQLite unde
32170 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61  rstands the X pa
32180 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
32190 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
321a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
321b0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
321c0 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ] as a zero-term
321d0 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
321e0 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
321f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73  in which case is
32200 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43   ignored for ASC
32210 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  II characters an
32220 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
32230 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72   significant for
32240 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61   non-ASCII chara
32250 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  cters..**.** {F1
32260 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65  6606} Successive
32270 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
32280 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32290 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
322a0 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
322b0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
322c0 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20  alues for B, X, 
322d0 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20  and E, override 
322e0 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20  prior values.** 
322f0 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46           of P, F
32300 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  , and D..**.** {
32310 46 31 36 36 30 39 7d 20 54 68 65 20 64 65 73 74  F16609} The dest
32320 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
32330 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32340 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
32350 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
32360 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
32370 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
32380 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
32390 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
323a0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
323b0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
323c0 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
323d0 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20  *.** {F16612} A 
323e0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
323f0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
32400 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
32410 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  ded..**.** {F166
32420 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
32430 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
32440 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
32450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
32470 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
32480 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
32490 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54  **.** {F16618} T
324a0 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
324b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
324c0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
324d0 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
324e0 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
324f0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
32500 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
32510 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
32520 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
32530 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
32540 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
32550 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
32560 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63  .** {F16621} A c
32570 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
32580 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32590 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
325a0 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
325b0 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
325c0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
325d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
325e0 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
325f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
32600 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
32610 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
32620 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ctor..**.** {F16
32630 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
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 42 2c  _collation_v2(B,
32660 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
32670 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
32680 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
32690 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
326a0 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
326b0 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
326c0 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
326d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
326e0 63 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74  ction] B on text
326f0 20 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20   values that.** 
32700 20 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65           use the
32710 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
32720 6e 63 65 20 6e 61 6d 65 20 58 2e 0a 2a 2a 0a 2a  nce name X..**.*
32730 2a 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b  * {F16627} The [
32740 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32750 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45  ollation16(B,X,E
32760 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65  ,P,F)] works the
32770 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
32780 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72    as [sqlite3_cr
32790 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42  eate_collation(B
327a0 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70  ,X,E,P,F)] excep
327b0 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  t that the.**   
327c0 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e         collation
327d0 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72   name X is under
327e0 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20  stood as UTF-16 
327f0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
32800 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
32810 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
32820 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30  8..**.** {F16630
32830 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  } When multiple 
32840 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
32850 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
32860 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a  le for the same.
32870 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
32880 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20  ating sequence, 
32890 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74  SQLite chooses t
328a0 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78  he one whose tex
328b0 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20  t encoding.**   
328c0 20 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20         requires 
328d0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
328e0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66   of conversion f
328f0 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a  rom the default.
32900 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
32910 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
32920 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e   database..*/.in
32930 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32940 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
32950 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
32960 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
32970 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
32980 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
32990 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
329a0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
329b0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
329c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
329d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
329e0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
329f0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
32a00 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
32a10 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
32a20 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
32a30 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
32a40 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
32a50 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
32a60 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
32a70 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
32a80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32a90 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
32aa0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
32ab0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
32ac0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
32ad0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
32ae0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
32af0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
32b00 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
32b10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32b20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
32b30 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37   Callbacks {F167
32b40 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00}.**.** To avo
32b50 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
32b60 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
32b70 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
32b80 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
32b90 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
32ba0 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
32bb0 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
32bc0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
32bd0 68 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  h the.** databas
32be0 65 20 68 61 6e 64 6c 65 20 74 6f 20 62 65 20 63  e handle to be c
32bf0 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61  alled whenever a
32c00 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
32c10 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
32c20 73 0a 2a 2a 20 72 65 71 75 69 72 65 64 2e 0a 2a  s.** required..*
32c30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63  *.** If the func
32c40 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
32c50 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
32c60 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32c70 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
32c80 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
32c90 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
32ca0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
32cb0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
32cc0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
32cd0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46 31  ed in UTF-8. {F1
32ce0 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33  6703} If sqlite3
32cf0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
32d00 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74  d16() is used, t
32d10 68 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20  he names.** are 
32d20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
32d30 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
32d40 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41  ve byte order. A
32d50 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a   call to either.
32d60 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  ** function repl
32d70 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e  aces any existin
32d80 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  g callback..**.*
32d90 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
32da0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
32db0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
32dc0 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
32dd0 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
32de0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
32df0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32e00 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
32e10 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
32e20 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
32e30 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
32e40 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
32e50 62 61 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20  base.** handle. 
32e60 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
32e70 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
32e80 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
32e90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
32ea0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
32eb0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
32ec0 67 20 74 68 65 20 6d 6f 73 74 0a 2a 2a 20 64 65  g the most.** de
32ed0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
32ee0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
32ef0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
32f00 72 65 71 75 69 72 65 64 2e 0a 2a 2a 20 54 68 65  required..** The
32f10 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
32f20 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
32f30 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
32f40 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
32f50 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
32f60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
32f70 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
32f80 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
32f90 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
32fa0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32fb0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
32fc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32fd0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
32fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
32ff0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33000 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
33010 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
33020 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66  6702} A successf
33030 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
33040 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33050 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20  eded(D,P,F)].** 
33060 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
33070 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33080 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20  eeded16(D,P,F)] 
33090 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20  causes.**       
330a0 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
330b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
330c0 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63  o invoke callbac
330d0 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a  k F with first.*
330e0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
330f0 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20  eter P whenever 
33100 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61  it needs a compa
33110 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66  rison function f
33120 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  or a.**         
33130 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
33140 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73  nce that it does
33150 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e   not know about.
33160 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 34 7d 20  .**.** {F16704} 
33170 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20  Each successful 
33180 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33190 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
331a0 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  d()] or.**      
331b0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
331c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
331d0 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
331e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74   callback regist
331f0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
33200 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
33210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33220 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  n] by prior call
33230 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20  s to either.**  
33240 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
33250 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 36  e..**.** {F16706
33260 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  } The name of th
33270 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c  e requested coll
33280 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  ating function p
33290 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  assed in the.** 
332a0 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72           4th par
332b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
332c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46  llback is in UTF
332d0 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  -8 if the callba
332e0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ck.**          w
332f0 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  as registered us
33300 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
33310 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
33320 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
33330 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61   is in UTF-16 na
33340 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
33350 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  if the callback 
33360 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
33370 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
33380 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
33390 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
333a0 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a 69 6e 74 20 73  .**.** .*/.int s
333b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
333c0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
333d0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
333e0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
333f0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
33400 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
33410 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
33420 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33430 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
33440 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
33450 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
33460 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
33470 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
33480 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
33490 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
334a0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
334b0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
334c0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
334d0 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
334e0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
334f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
33500 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
33510 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
33520 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
33530 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
33540 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
33550 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
33560 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
33570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33580 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
33590 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
335a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
335b0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
335c0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
335d0 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
335e0 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
335f0 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
33600 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
33610 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
33620 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
33630 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
33640 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
33650 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
33660 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
33670 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
33680 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
33690 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
336a0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
336b0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
336c0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
336d0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
336e0 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
336f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
33700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
33710 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
33720 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
33730 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
33740 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
33750 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
33760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33770 3a 20 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  :  Suspend Execu
33780 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
33790 20 54 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a   Time {F10530}.*
337a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
337b0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
337c0 6e 0a 2a 2a 20 63 61 75 73 65 73 20 74 68 65 20  n.** causes the 
337d0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
337e0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
337f0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
33800 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
33810 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
33820 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
33830 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
33840 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
33850 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
33860 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
33870 71 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20  quests with .** 
33880 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
33890 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
338a0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
338b0 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
338c0 20 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74   .** the nearest
338d0 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
338e0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
338f0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
33900 75 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73  ually .** reques
33910 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
33920 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
33930 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
33940 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
33950 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
33960 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
33970 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
33980 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
33990 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
339a0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
339b0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
339c0 20 7b 46 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {F10533} The [s
339d0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
339e0 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
339f0 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
33a00 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
33a10 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
33a20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
33a30 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
33a40 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
33a50 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
33a60 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
33a70 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
33a80 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
33a90 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
33aa0 20 7b 46 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {F10536} The [s
33ab0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
33ac0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
33ad0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
33ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
33af0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
33b00 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
33b10 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
33b20 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
33b30 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
33b40 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
33b50 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
33b60 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
33b70 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
33b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33b90 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  F:  Name Of The 
33ba0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
33bb0 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b  emporary Files {
33bc0 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66  F10310}.**.** If
33bd0 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
33be0 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
33bf0 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
33c00 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
33c10 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
33c20 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
33c30 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
33c40 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
33c50 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
33c60 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c  QLite will be pl
33c70 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
33c80 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73  ectory.  If this
33c90 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
33ca0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
33cb0 65 6e 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61  en SQLite does a
33cc0 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
33cd0 70 70 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f  ppropriate tempo
33ce0 72 61 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72  rary.** file dir
33cf0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
33d00 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
33d10 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
33d20 61 62 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61  able once a data
33d30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
33d40 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e  ** has been open
33d50 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e  ed.  It is inten
33d60 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
33d70 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
33d80 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
33d90 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
33da0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
33db0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
33dc0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
33dd0 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
33de0 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e  ll and remain un
33df0 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74  changed thereaft
33e00 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  er..*/.SQLITE_EX
33e10 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
33e20 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
33e30 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
33e40 45 46 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65  EF:  Test To See
33e50 20 49 66 20 54 68 65 20 44 61 74 61 62 61 73 65   If The Database
33e60 20 49 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d   Is In Auto-Comm
33e70 69 74 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d  it Mode {F12930}
33e80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33e90 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
33ea0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
33eb0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
33ec0 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
33ed0 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
33ee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
33ef0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
33f00 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
33f10 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41  espectively.   A
33f20 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
33f30 73 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75  s on.** by defau
33f40 6c 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  lt.  Autocommit 
33f50 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
33f60 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
33f70 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f  atement..** Auto
33f80 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
33f90 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
33fa0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
33fb0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
33fc0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
33fd0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
33fe0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
33ff0 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
34000 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
34010 74 69 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e  tions (errors in
34020 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
34030 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
34040 4f 45 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  OERR], .** [SQLI
34050 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
34060 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
34070 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
34080 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
34090 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
340a0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
340b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
340c0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
340d0 2a 20 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51  * find out if SQ
340e0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
340f0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
34100 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
34110 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
34120 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
34130 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
34140 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
34150 2a 20 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b  * {F12931} The [
34160 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
34170 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72  commit(D)] inter
34180 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
34190 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20  -zero or.**     
341a0 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65       zero if the
341b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
341c0 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69  ction] D is or i
341d0 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
341e0 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mit.**          
341f0 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65  mode, respective
34200 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  ly..**.** {F1293
34210 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  2} Autocommit mo
34220 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
34230 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ult..**.** {F129
34240 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  33} Autocommit m
34250 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
34260 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  by a successful 
34270 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
34280 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34  t..**.** {F12934
34290 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
342a0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20  e is enabled by 
342b0 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f  a successful [CO
342c0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
342d0 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  CK].**          
342e0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a  statement..** .*
342f0 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
34300 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36  :.***.** {U12936
34310 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
34320 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
34330 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
34340 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
34350 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
34360 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
34370 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
34380 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
34390 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
343a0 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64            is und
343b0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
343c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
343d0 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
343e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
343f0 3a 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  :  Find The Data
34400 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
34410 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
34420 65 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a  ent {F13120}.**.
34430 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
34440 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
34450 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  ce.** returns th
34460 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20 64 61 74  e [sqlite3*] dat
34470 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f 20  abase handle to 
34480 77 68 69 63 68 20 61 0a 2a 2a 20 5b 70 72 65 70  which a.** [prep
34490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
344a0 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  belongs..** The 
344b0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
344c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
344d0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a  te3_db_handle.**
344e0 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74   is the same dat
344f0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61  abase handle tha
34500 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72  t was.** the fir
34510 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
34520 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
34530 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
34540 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61   variants.** tha
34550 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72  t was used to cr
34560 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
34570 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
34580 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  place..**.** INV
34590 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
345a0 46 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c  F13123} The [sql
345b0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53  ite3_db_handle(S
345c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
345d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
345e0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
345f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34600 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  ection] associat
34610 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ed with.**      
34620 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
34630 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73  atement] S..*/.s
34640 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
34650 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
34660 33 5f 73 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a  3_stmt*);.../*.*
34670 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
34680 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
34690 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
346a0 6c 62 61 63 6b 73 20 7b 46 31 32 39 35 30 7d 0a  lbacks {F12950}.
346b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
346c0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
346d0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
346e0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
346f0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
34700 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
34710 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
34720 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
34730 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
34740 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
34750 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34760 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
34770 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
34780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34790 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
347a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
347b0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
347c0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
347d0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
347e0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
347f0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
34800 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
34810 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a  is committed..**
34820 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
34830 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
34840 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34850 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
34860 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
34870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34880 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
34890 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61 72 67  .** The pArg arg
348a0 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
348b0 74 68 72 6f 75 67 68 0a 2a 2a 20 74 6f 20 74 68  through.** to th
348c0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20  e callback.  If 
348d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
348e0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
348f0 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75 72  nction .** retur
34900 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
34910 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
34920 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
34930 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
34940 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
34950 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
34960 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
34970 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75  its.** pArg valu
34980 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
34990 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
349a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
349b0 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20  * Registering a 
349c0 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
349d0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
349e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
349f0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
34a00 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
34a10 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
34a20 6f 20 68 61 76 65 20 62 65 65 6e 20 0a 2a 2a 20  o have been .** 
34a30 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
34a40 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
34a50 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
34a60 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
34a70 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
34a80 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
34a90 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
34aa0 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
34ab0 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  ** The rollback 
34ac0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
34ad0 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61  invoked if a tra
34ae0 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61  nsaction is.** a
34af0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
34b00 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
34b10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
34b20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
34b30 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ed..** The rollb
34b40 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
34b50 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
34b60 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
34b70 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
34b80 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
34b90 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
34ba0 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c  d non-zero..** <
34bb0 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74  todo> Check on t
34bc0 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  his </todo>.**.*
34bd0 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70 65  * These are expe
34be0 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
34bf0 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62 6a  ces and are subj
34c00 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a 2a  ect to change..*
34c10 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34c20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d 20  .**.** {F12951} 
34c30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  The [sqlite3_com
34c40 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
34c50 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
34c60 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
34c70 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
34c80 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
34c90 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
34ca0 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
34cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
34cc0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
34cd0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
34ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
34cf0 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 54 68 65  .** {F12952} The
34d00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
34d10 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
34d20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34d30 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20  the P.**        
34d40 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20    argument from 
34d50 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
34d60 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  l with the same 
34d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
34d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34d90 6e 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20  n ] D , or NULL 
34da0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  on the first cal
34db0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  l.**          fo
34dc0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b  r a particular [
34dd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34de0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
34df0 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c  12953} Each call
34e00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
34e10 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72  mit_hook()] over
34e20 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62  writes the callb
34e30 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
34e40 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72  registered by pr
34e50 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a  ior calls..**.**
34e60 20 7b 46 31 32 39 35 34 7d 20 49 66 20 74 68 65   {F12954} If the
34e70 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b   F argument to [
34e80 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
34e90 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e  ook(D,F,P)] is N
34ea0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
34eb0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
34ec0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
34ed0 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f   canceled and no
34ee0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
34ef0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
34f00 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
34f10 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a  ion commits..**.
34f20 2a 2a 20 7b 46 31 32 39 35 35 7d 20 49 66 20 74  ** {F12955} If t
34f30 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61  he commit callba
34f40 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
34f50 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  ero then the com
34f60 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  mit is.**       
34f70 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74     converted int
34f80 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
34f90 0a 2a 2a 20 7b 46 31 32 39 36 31 7d 20 54 68 65  .** {F12961} The
34fa0 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
34fb0 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
34fc0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
34fd0 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
34fe0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
34ff0 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
35000 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
35010 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
35020 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
35030 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
35040 61 63 6b 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ack on [database
35050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
35060 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 32 7d 20 54  **.** {F12962} T
35070 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
35080 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
35090 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
350a0 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20  rns the P.**    
350b0 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66        argument f
350c0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
350d0 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
350e0 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame .**         
350f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35100 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20 4e  ction ] D , or N
35110 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
35120 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
35130 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
35140 61 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ar [database con
35150 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
35160 2a 20 7b 46 31 32 39 36 33 7d 20 45 61 63 68 20  * {F12963} Each 
35170 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35180 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
35190 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
351a0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
351b0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
351c0 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
351d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 34 7d 20  .**.** {F12964} 
351e0 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
351f0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
35200 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
35210 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
35220 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
35230 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
35240 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
35250 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
35260 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
35270 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
35280 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
35290 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69  lls back..*/.voi
352a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
352b0 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
352c0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
352d0 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
352e0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
352f0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
35300 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
35310 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
35320 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
35330 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
35340 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
35350 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  70}.**.** The sq
35360 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35370 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  k() interface.**
35380 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
35390 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
353a0 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
353b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
353c0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  tified by the .*
353d0 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  * first argument
353e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
353f0 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
35400 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
35410 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
35420 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
35430 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
35440 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
35450 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 73  nction for the s
35460 61 6d 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  ame .** database
35470 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
35480 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
35490 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
354a0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
354b0 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
354c0 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
354d0 20 61 20 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70   a .** row is up
354e0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
354f0 6f 72 20 64 65 6c 65 74 65 64 2e 20 0a 2a 2a 20  or deleted. .** 
35500 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
35510 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
35520 63 6b 20 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20  ck is.** a copy 
35530 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
35540 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
35550 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
35560 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61  ** The second ca
35570 6c 6c 62 61 63 6b 20 0a 2a 2a 20 61 72 67 75 6d  llback .** argum
35580 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
35590 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
355a0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f  SQLITE_DELETE] o
355b0 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
355c0 5d 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20  ],.** depending 
355d0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
355e0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
355f0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
35600 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20  invoked..** The 
35610 74 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f  third and .** fo
35620 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
35630 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
35640 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
35650 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
35660 61 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61  and .** table na
35670 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
35680 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
35690 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
356a0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
356b0 69 73 20 0a 2a 2a 20 74 68 65 20 72 6f 77 69 64  is .** the rowid
356c0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
356d0 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
356e0 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
356f0 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65  s the rowid afte
35700 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74 65  r .** the update
35710 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
35720 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
35730 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
35740 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
35750 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
35760 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
35770 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
35780 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
35790 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
357a0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
357b0 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
357c0 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
357d0 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20  s pArg value.** 
357e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
357f0 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
35800 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
35810 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
35820 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20 5b  * {F12971} The [
35830 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
35840 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
35850 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
35860 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
35870 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20    function F to 
35880 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
35890 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
358a0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
358b0 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72         a table r
358c0 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20  ow is modified, 
358d0 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c  inserted, or del
358e0 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20  eted on.**      
358f0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
35900 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
35910 2a 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20  ** {F12973} The 
35920 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
35930 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
35940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
35950 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
35960 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68       of P for th
35970 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
35980 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
35990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
359a0 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] D,.**         
359b0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65   or NULL for the
359c0 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a   first call..**.
359d0 2a 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74  ** {F12975} If t
359e0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
359f0 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71  allback F in [sq
35a00 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35a10 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20  k(D,F,P)].**    
35a20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68        is NULL th
35a30 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65  en the no update
35a40 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d   callbacks are m
35a50 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ade..**.** {F129
35a60 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  77} Each call to
35a70 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
35a80 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76  _hook(D,F,P)] ov
35a90 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61  errides prior ca
35aa0 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
35ab0 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65  to the same inte
35ac0 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d  rface on the sam
35ad0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35ae0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
35af0 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70   {F12979} The up
35b00 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
35b10 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
35b20 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
35b30 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20  system.**       
35b40 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61     tables such a
35b50 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  s sqlite_master 
35b60 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
35b70 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64  nce are modified
35b80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d  ..**.** {F12981}
35b90 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
35ba0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64  meter to the upd
35bb0 61 74 65 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ate callback .**
35bc0 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65            is one
35bd0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
35be0 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
35bf0 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ETE] or [SQLITE_
35c00 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20  UPDATE],.**     
35c10 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f       depending o
35c20 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
35c30 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
35c40 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69  callback to be i
35c50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nvoked..**.** {F
35c60 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64  12983} The third
35c70 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
35c80 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
35c90 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
35ca0 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  inters.**       
35cb0 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69     to zero-termi
35cc0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
35cd0 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68  ngs which are th
35ce0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  e names of the.*
35cf0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
35d00 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68  ase and table th
35d10 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61  at is being upda
35d20 74 65 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35  ted...** {F12985
35d30 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  } The final call
35d40 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
35d50 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
35d60 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20  he row after.** 
35d70 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61           the cha
35d80 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76  nge occurs..*/.v
35d90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64  oid *sqlite3_upd
35da0 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69  ate_hook(.  sqli
35db0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  te3*, .  void(*)
35dc0 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61  (void *,int ,cha
35dd0 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63  r const *,char c
35de0 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69  onst *,sqlite3_i
35df0 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29  nt64),.  void*.)
35e00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35e10 46 3a 20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  F:  Enable Or Di
35e20 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
35e30 65 72 20 43 61 63 68 65 20 7b 46 31 30 33 33 30  er Cache {F10330
35e40 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
35e50 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
35e60 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
35e70 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
35e80 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
35e90 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
35ea0 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
35eb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f 20   connections to 
35ec0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35ed0 65 2e 0a 2a 2a 20 53 68 61 72 69 6e 67 20 69 73  e..** Sharing is
35ee0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
35ef0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
35f00 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
35f10 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
35f20 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a   is false..**.**
35f30 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69   Cache sharing i
35f40 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
35f50 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e  sabled.** for an
35f60 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
35f70 20 7b 45 4e 44 7d 20 54 68 69 73 20 69 73 20 61   {END} This is a
35f80 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
35f90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
35fa0 2e 30 2e 0a 2a 2a 20 49 6e 20 70 72 69 6f 72 20  .0..** In prior 
35fb0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
35fc0 74 65 2c 20 73 68 61 72 69 6e 67 20 77 61 73 0a  te, sharing was.
35fd0 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  ** enabled or di
35fe0 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
35ff0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
36000 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63  y..**.** The cac
36010 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
36020 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
36030 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
36040 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
36050 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36060 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
36070 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
36080 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
36090 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
360a0 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
360b0 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
360c0 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
360d0 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
360e0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
360f0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
36100 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  re opened..**.**
36110 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
36120 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77  cannot be used w
36130 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63  ith a shared cac
36140 68 65 2e 20 20 20 57 68 65 6e 20 73 68 61 72 65  he.   When share
36150 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
36160 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
36170 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36180 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f  e()] API used to
36190 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
361a0 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
361b0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
361c0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
361d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
361e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
361f0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
36200 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f  was.** enabled o
36210 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
36220 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
36230 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 69 73 20  ror code].** is 
36240 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
36250 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64  se..**.** Shared
36260 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
36270 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
36280 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
36290 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
362a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
362b0 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
362c0 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
362d0 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
362e0 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
362f0 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
36300 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  itly..**.** INVA
36310 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b  RIANTS:.** .** {
36320 46 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73  F10331} A succes
36330 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
36340 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  of [sqlite3_enab
36350 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
36360 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  B)].**          
36370 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64  will enable or d
36380 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61  isable shared ca
36390 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79  che mode for any
363a0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a   subsequently.**
363b0 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65            create
363c0 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
363d0 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73  ection] in the s
363e0 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a  ame process..**.
363f0 2a 2a 20 7b 46 31 30 33 33 36 7d 20 57 68 65 6e  ** {F10336} When
36400 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73   shared cache is
36410 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
36420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
36430 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dule()].**      
36440 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69      interface wi
36450 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
36460 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
36470 20 7b 46 31 30 33 33 37 7d 20 54 68 65 20 5b 73   {F10337} The [s
36480 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
36490 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69  ared_cache(B)] i
364a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
364b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
364c0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
364d0 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
364e0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
364f0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a   successfully..*
36500 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68  *.** {F10339} Sh
36510 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
36520 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
36530 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
36540 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
36550 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
36560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 41 74  ** CAPI3REF:  At
36570 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
36580 61 70 20 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34  ap Memory {F1734
36590 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
365a0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
365b0 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
365c0 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 66  attempts to.** f
365d0 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68  ree N bytes of h
365e0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
365f0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
36600 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 0a  ssential memory.
36610 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68  ** allocations h
36620 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
36630 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e  ase library. {EN
36640 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 0a  D}  Memory used.
36650 2a 2a 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ** to cache data
36660 62 61 73 65 20 70 61 67 65 73 20 74 6f 20 69 6d  base pages to im
36670 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
36680 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
36690 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65 73 73 65 6e 74  of.** non-essent
366a0 69 61 6c 20 6d 65 6d 6f 72 79 2e 20 20 53 71 6c  ial memory.  Sql
366b0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
366c0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ory() returns.**
366d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
366e0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
366f0 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74  eed, which might
36700 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
36710 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  .** than the amo
36720 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
36730 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
36740 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20  .**.** {F17341} 
36750 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
36760 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
36770 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36780 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ts to.**        
36790 20 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f    free N bytes o
367a0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
367b0 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
367c0 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20  n-essential.**  
367d0 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61          memory a
367e0 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20  llocations held 
367f0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
36800 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b  library..**.** {
36810 46 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16342} The [sql
36820 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
36830 6f 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20  ory(N)] returns 
36840 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  the number.**   
36850 20 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20         of bytes 
36860 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20  actually freed, 
36870 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
36880 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20  ore or less.**  
36890 20 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65          than the
368a0 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
368b0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
368c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
368d0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
368e0 50 49 33 52 45 46 3a 20 20 49 6d 70 6f 73 65 20  PI3REF:  Impose 
368f0 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
36900 53 69 7a 65 20 7b 46 31 37 33 35 30 7d 0a 2a 2a  Size {F17350}.**
36910 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36920 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
36930 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 70  ) interface.** p
36940 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
36950 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75  imit on the amou
36960 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
36970 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
36980 6c 6f 63 61 74 65 64 0a 2a 2a 20 62 79 20 53 51  located.** by SQ
36990 4c 69 74 65 2e 20 49 66 20 61 6e 20 69 6e 74 65  Lite. If an inte
369a0 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
369b0 69 73 20 72 65 71 75 65 73 74 65 64 20 0a 2a 2a  is requested .**
369c0 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
369d0 65 64 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ed the soft heap
369e0 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33   limit, [sqlite3
369f0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36a00 29 5d 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  )] is.** invoked
36a10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
36a20 65 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f  es to free up so
36a30 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20  me space before 
36a40 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  the allocation.*
36a50 2a 20 69 73 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a  * is made..**.**
36a60 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61   The limit is ca
36a70 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65 63  lled "soft", bec
36a80 61 75 73 65 20 69 66 0a 2a 2a 20 5b 73 71 6c 69  ause if.** [sqli
36a90 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
36aa0 72 79 28 29 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ry()] cannot.** 
36ab0 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74 20  free sufficient 
36ac0 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e  memory to preven
36ad0 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d  t the limit from
36ae0 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c   being exceeded,
36af0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69  .** the memory i
36b00 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77  s allocated anyw
36b10 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72 65  ay and the curre
36b20 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  nt operation pro
36b30 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e  ceeds..**.** A n
36b40 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20  egative or zero 
36b50 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e  value for N mean
36b60 73 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  s that there is 
36b70 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  no soft heap lim
36b80 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  it and.** [sqlit
36b90 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
36ba0 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62  y()] will only b
36bb0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65  e called when me
36bc0 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65  mory is exhauste
36bd0 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
36be0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
36bf0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
36c00 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  is zero..**.** S
36c10 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65  QLite makes a be
36c20 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e  st effort to hon
36c30 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
36c40 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 42 75 74   limit.  .** But
36c50 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
36c60 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62  p limit cannot b
36c70 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75  e honored, execu
36c80 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
36c90 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
36ca0 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
36cb0 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68  ion.  This is wh
36cc0 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 0a  y the limit is .
36cd0 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66  ** called a "sof
36ce0 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73  t" limit.  It is
36cf0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
36d00 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
36d10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
36d20 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  5.0, this routin
36d30 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e  e only constrain
36d40 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ed the memory.**
36d50 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20   allocated by a 
36d60 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20  single thread - 
36d70 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
36d80 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f  in which this ro
36d90 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20  utine.** runs.  
36da0 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53  Beginning with S
36db0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
36dc0 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65  5.0, the soft he
36dd0 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61  ap limit is.** a
36de0 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68  pplied to all th
36df0 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65  reads. The value
36e00 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74   specified for t
36e10 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
36e20 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65  it.** is an uppe
36e30 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74  r bound on the t
36e40 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  otal memory allo
36e50 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74  cation for all t
36e60 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65  hreads. In.** ve
36e70 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72  rsion 3.5.0 ther
36e80 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73  e is no mechanis
36e90 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74  m for limiting t
36ea0 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f  he heap usage fo
36eb0 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20  r.** individual 
36ec0 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49  threads..**.** I
36ed0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36ee0 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73   {F16351} The [s
36ef0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
36f00 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72  _limit(N)] inter
36f10 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f  face places a so
36f20 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20  ft limit.**     
36f30 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20       of N bytes 
36f40 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
36f50 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
36f60 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
36f70 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  ed.**          u
36f80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
36f90 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
36fa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61  te3_realloc()] a
36fb0 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20  t any point.**  
36fc0 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e          in time.
36fd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20  .**.** {F16352} 
36fe0 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
36ff0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
37000 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
37010 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20  loc()] would.** 
37020 20 20 20 20 20 20 20 20 20 63 61 75 73 65 20 74           cause t
37030 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20  he total amount 
37040 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d  of allocated mem
37050 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20 74 68  ory to exceed th
37060 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f  e.**          so
37070 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74  ft heap limit, t
37080 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  hen [sqlite3_rel
37090 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
370a0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
370b0 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65        in an atte
370c0 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20 74 68  mpt to reduce th
370d0 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70  e memory usage p
370e0 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69  rior to proceedi
370f0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ng.**          w
37100 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ith the memory a
37110 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70  llocation attemp
37120 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33  t..**.** {F16353
37130 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
37140 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
37150 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
37160 63 28 29 5d 20 74 68 61 74 20 74 72 69 67 67 65  c()] that trigge
37170 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  r.**          at
37180 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65  tempts to reduce
37190 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68   memory usage th
371a0 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74 20 68  rough the soft h
371b0 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20  eap limit.**    
371c0 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20        mechanism 
371d0 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66  continue even if
371e0 20 74 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20   the attempt to 
371f0 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a  reduce memory.**
37200 20 20 20 20 20 20 20 20 20 20 75 73 61 67 65 20            usage 
37210 69 73 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e  is unsuccessful.
37220 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20  .**.** {F16354} 
37230 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65  A negative or ze
37240 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69  ro value for N i
37250 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20  n a call to.**  
37260 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
37270 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37280 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  (N)] means that 
37290 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
372a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 65 61  .**          hea
372b0 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c  p limit and [sql
372c0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
372d0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
372e0 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
372f0 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
37300 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79  ry is completely
37310 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a   exhausted..**.*
37320 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64  * {F16355} The d
37330 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
37340 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37350 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
37360 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63  .** {F16358} Eac
37370 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
37380 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37390 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73  it(N)] overrides
373a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
373b0 20 76 61 6c 75 65 73 20 73 65 74 20 62 79 20 61   values set by a
373c0 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  ll prior calls..
373d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
373e0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
373f0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
37400 49 33 52 45 46 3a 20 20 45 78 74 72 61 63 74 20  I3REF:  Extract 
37410 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
37420 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
37430 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a  le {F12850}.**.*
37440 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  * This routine.*
37450 2a 20 72 65 74 75 72 6e 73 20 6d 65 74 61 2d 64  * returns meta-d
37460 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
37470 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
37480 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
37490 73 65 0a 2a 2a 20 74 61 62 6c 65 20 61 63 63 65  se.** table acce
374a0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
374b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   connection hand
374c0 6c 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  le passed as the
374d0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
374e0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  .** argument..**
374f0 0a 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69  .** The column i
37500 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
37510 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
37520 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
37530 61 6d 65 74 65 72 73 20 74 6f 20 0a 2a 2a 20 74  ameters to .** t
37540 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
37550 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
37560 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
37570 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
37580 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
37590 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72  main", "temp" or
375a0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
375b0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
375c0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
375d0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
375e0 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
375f0 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
37600 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
37610 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
37620 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
37630 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
37640 74 68 6d 20 61 73 20 74 68 65 20 64 61 74 61 62  thm as the datab
37650 61 73 65 20 65 6e 67 69 6e 65 20 75 73 65 73 20  ase engine uses 
37660 74 6f 20 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75  to .** resolve u
37670 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
37680 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
37690 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
376a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
376b0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
376c0 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
376d0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 0a 2a 2a  e and column .**
376e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
376f0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
37700 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
37710 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
37720 6d 65 74 65 72 73 20 0a 2a 2a 20 6d 61 79 20 62  meters .** may b
37730 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65  e NULL..**.** Me
37740 74 61 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ta information i
37750 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
37760 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
37770 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
37780 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 35  ssed as.** the 5
37790 74 68 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  th and subsequen
377a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
377b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 41  this function. A
377c0 6e 79 20 6f 66 20 74 68 65 73 65 20 0a 2a 2a 20  ny of these .** 
377d0 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
377e0 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
377f0 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
37800 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
37810 66 20 6d 65 74 61 20 0a 2a 2a 20 69 6e 66 6f 72  f meta .** infor
37820 6d 61 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  mation is omitte
37830 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  d..**.** <pre>.*
37840 2a 20 50 61 72 61 6d 65 74 65 72 20 20 20 20 20  * Parameter     
37850 4f 75 74 70 75 74 20 54 79 70 65 20 20 20 20 20  Output Type     
37860 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   Description.** 
37870 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
37880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
37890 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20 20 35 74 68 20  ---.**.**   5th 
378a0 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63 68          const ch
378b0 61 72 2a 20 20 20 20 20 20 44 61 74 61 20 74 79  ar*      Data ty
378c0 70 65 0a 2a 2a 20 20 20 36 74 68 20 20 20 20 20  pe.**   6th     
378d0 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20      const char* 
378e0 20 20 20 20 20 4e 61 6d 65 20 6f 66 20 74 68 65       Name of the
378f0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
37900 6f 6e 20 73 65 71 75 65 6e 63 65 20 0a 2a 2a 20  on sequence .** 
37910 20 20 37 74 68 20 20 20 20 20 20 20 20 20 69 6e    7th         in
37920 74 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54  t              T
37930 72 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d  rue if the colum
37940 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
37950 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 20   constraint.**  
37960 20 38 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   8th         int
37970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
37980 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
37990 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
379a0 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 20  PRIMARY KEY.**  
379b0 20 39 74 68 20 20 20 20 20 20 20 20 20 69 6e 74   9th         int
379c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 54 72                Tr
379d0 75 65 20 69 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ue if the column
379e0 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e   is AUTOINCREMEN
379f0 54 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a  T.** </pre>.**.*
37a00 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
37a10 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
37a20 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
37a30 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
37a40 72 20 74 68 65 20 0a 2a 2a 20 64 65 63 6c 61 72  r the .** declar
37a50 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
37a60 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37a70 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
37a80 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 0a  until the next .
37a90 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 73  ** call to any s
37aa0 71 6c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  qlite API functi
37ab0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
37ac0 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
37ad0 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
37ae0 69 65 77 2c 20 74 68 65 6e 20 61 6e 20 65 72 72  iew, then an err
37af0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
37b00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65  **.** If the spe
37b10 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
37b20 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
37b30 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
37b40 20 61 6e 20 0a 2a 2a 20 49 4e 54 45 47 45 52 20   an .** INTEGER 
37b50 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75  PRIMARY KEY colu
37b60 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
37b70 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
37b80 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
37b90 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20   .** parameters 
37ba0 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
37bb0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
37bc0 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74  red column. If t
37bd0 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
37be0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
37bf0 64 20 49 50 4b 20 63 6f 6c 75 6d 6e 2c 20 74 68  d IPK column, th
37c00 65 6e 20 74 68 65 20 6f 75 74 70 75 74 20 70 61  en the output pa
37c10 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
37c20 20 61 73 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 73 3a   as .** follows:
37c30 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
37c40 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
37c50 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
37c60 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37c70 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
37c80 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
37c90 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
37ca0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
37cb0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
37cc0 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54  * </pre>.**.** T
37cd0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
37ce0 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
37cf0 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
37d00 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
37d10 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
37d20 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
37d30 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
37d40 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
37d50 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
37d60 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
37d70 2c 20 61 6e 20 53 51 4c 49 54 45 20 65 72 72 6f  , an SQLITE erro
37d80 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
37d90 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
37da0 6d 65 73 73 61 67 65 0a 2a 2a 20 6c 65 66 74 20  message.** left 
37db0 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
37dc0 68 61 6e 64 6c 65 20 28 74 6f 20 62 65 20 72 65  handle (to be re
37dd0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
37de0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
37df0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
37e00 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
37e10 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
37e20 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
37e30 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
37e40 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
37e50 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
37e60 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
37e70 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
37e80 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
37e90 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
37ea0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
37eb0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
37ec0 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
37ed0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37ee0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
37ef0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
37f00 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
37f10 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
37f20 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
37f30 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
37f40 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
37f50 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
37f60 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
37f70 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
37f80 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
37f90 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
37fa0 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
37fb0 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
37fc0 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
37fd0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
37fe0 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
37ff0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
38000 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
38010 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
38020 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
38030 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
38040 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
38050 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
38060 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
38070 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
38080 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
38090 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
380a0 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
380b0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
380c0 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
380d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
380e0 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
380f0 73 69 6f 6e 20 7b 46 31 32 36 30 30 7d 0a 2a 2a  sion {F12600}.**
38100 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68 65  .** {F12601} The
38110 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
38120 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
38130 61 63 65 0a 2a 2a 20 61 74 74 65 6d 70 74 73 20  ace.** attempts 
38140 74 6f 20 6c 6f 61 64 20 61 6e 20 53 51 4c 69 74  to load an SQLit
38150 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
38160 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e  ary contained in
38170 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 7a 46 69   the file.** zFi
38180 6c 65 2e 20 7b 46 31 32 36 30 32 7d 20 54 68 65  le. {F12602} The
38190 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
381a0 7a 50 72 6f 63 2e 20 7b 46 31 32 36 30 33 7d 20  zProc. {F12603} 
381b0 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 0a 2a  zProc may be 0.*
381c0 2a 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  * in which case 
381d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
381e0 65 6e 74 72 79 20 70 6f 69 6e 74 20 64 65 66 61  entry point defa
381f0 75 6c 74 73 0a 2a 2a 20 74 6f 20 22 73 71 6c 69  ults.** to "sqli
38200 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
38210 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  it"..**.** {F126
38220 30 34 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  04} The sqlite3_
38230 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
38240 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
38250 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
38260 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
38270 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
38280 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
38290 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
382a0 0a 2a 2a 20 7b 46 31 32 36 30 35 7d 0a 2a 2a 20  .** {F12605}.** 
382b0 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
382c0 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20  rs and pzErrMsg 
382d0 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74  is not 0, then t
382e0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 6f  he.** sqlite3_lo
382f0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
38300 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
38310 74 74 65 6d 70 74 20 74 6f 20 66 69 6c 6c 20 2a  ttempt to fill *
38320 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 0a 2a  pzErrMsg with .*
38330 2a 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * error message 
38340 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d  text stored in m
38350 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
38360 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38370 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 7b 45 4e 44 7d  loc()]..** {END}
38380 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75    The calling fu
38390 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72  nction should fr
383a0 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a  ee this memory.*
383b0 2a 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  * by calling [sq
383c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
383d0 2a 0a 2a 2a 20 7b 46 31 32 36 30 36 7d 0a 2a 2a  *.** {F12606}.**
383e0 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   Extension loadi
383f0 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c  ng must be enabl
38400 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
38410 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
38420 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 70 72  tension()].** pr
38430 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
38440 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20 65 72  his API or an er
38450 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75  ror will be retu
38460 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
38470 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
38480 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
38490 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
384a0 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69  Load the extensi
384b0 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74  on into this dat
384c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
384d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
384e0 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e   *zFile,    /* N
384f0 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65  ame of the share
38500 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  d library contai
38510 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a  ning extension *
38520 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
38530 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74  zProc,    /* Ent
38540 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76  ry point.  Deriv
38550 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66  ed from zFile if
38560 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70   0 */.  char **p
38570 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a  zErrMsg       /*
38580 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61   Put error messa
38590 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30  ge here if not 0
385a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
385b0 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20  PI3REF:  Enable 
385c0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
385d0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31  sion Loading {F1
385e0 32 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 53 6f 20 61  2620}.**.** So a
385f0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
38600 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
38610 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
38620 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
38630 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
38640 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
38650 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
38660 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
38670 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
38680 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
38690 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
386a0 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
386b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 41  e following.** A
386c0 50 49 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  PI is provided t
386d0 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
386e0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
386f0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
38700 6f 6e 20 61 6e 64 0a 2a 2a 20 6f 66 66 2e 20 20  on and.** off.  
38710 7b 46 31 32 36 32 32 7d 20 49 74 20 69 73 20 6f  {F12622} It is o
38720 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 7b  ff by default. {
38730 45 4e 44 7d 20 53 65 65 20 74 69 63 6b 65 74 20  END} See ticket 
38740 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  #1863..**.** {F1
38750 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65 20 73  2621} Call the s
38760 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
38770 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
38780 6f 75 74 69 6e 65 0a 2a 2a 20 77 69 74 68 20 6f  outine.** with o
38790 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20  noff==1 to turn 
387a0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
387b0 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c  g on.** and call
387c0 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d   it with onoff==
387d0 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63  0 to turn it bac
387e0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 20 7b 45 4e  k off again. {EN
387f0 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D}.*/.int sqlite
38800 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
38810 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
38820 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
38830 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38840 3a 20 4d 61 6b 65 20 41 72 72 61 6e 67 65 6d 65  : Make Arrangeme
38850 6e 74 73 20 54 6f 20 41 75 74 6f 6d 61 74 69 63  nts To Automatic
38860 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
38870 65 6e 73 69 6f 6e 20 7b 46 31 32 36 34 30 7d 0a  ension {F12640}.
38880 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 31 7d 20 54  **.** {F12641} T
38890 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
388a0 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74  registers an ext
388b0 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69  ension entry poi
388c0 6e 74 20 74 68 61 74 20 69 73 20 61 75 74 6f 6d  nt that is autom
388d0 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
388e0 0a 2a 2a 20 77 68 65 6e 65 76 65 72 20 61 20 6e  .** whenever a n
388f0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
38900 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
38910 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
38920 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
38930 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
38940 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
38950 5f 76 32 28 29 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a  _v2()]. {END}.**
38960 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e  .** This API can
38970 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70   be invoked