Documentation Source Text

Hex Artifact Content
Login

Artifact 84594afba90558ff6b373d3d356b1e2798e02c47:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 74 6f  e changes .** to
0390: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
03a0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
03b0: 65 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e  erve to make min
03c0: 6f 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a  or changes if.**
03d0: 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d   experience from
03e0: 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c   use "in the wil
03f0: 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20  d" suggest such 
0400: 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64  changes are prud
0410: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  ent..**.** The o
0420: 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61  fficial C-langua
0430: 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61  ge API documenta
0440: 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20  tion for SQLite 
0450: 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72  is derived.** fr
0460: 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74  om comments in t
0470: 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20  his file.  This 
0480: 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68  file is the auth
0490: 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65  oritative source
04a0: 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74  .** on how SQLit
04b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
04c0: 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72   suppose to oper
04d0: 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ate..**.** The n
04e0: 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ame of this file
04f0: 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61   under configura
0500: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
0510: 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22  is "sqlite.h.in"
0520: 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c  ..** The makefil
0530: 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e  e makes some min
0540: 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  or changes to th
0550: 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73  is file (such as
0560: 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68   inserting.** th
0570: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
0580: 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74  ) and changes it
0590: 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74  s name to "sqlit
05a0: 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74  e3.h" as.** part
05b0: 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72   of the build pr
05c0: 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23  ocess..**.** @(#
05d0: 29 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e  ) $Id: sqlite.h.
05e0: 69 6e 2c 76 20 31 2e 32 37 36 20 32 30 30 37 2f  in,v 1.276 2007/
05f0: 31 32 2f 30 36 20 30 32 3a 34 32 3a 30 38 20 64  12/06 02:42:08 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 6f  SQLite is a stro
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 2d  VERSION_NUMBER -
0d80: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
0d90: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
0da0: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
0db0: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
0dc0: 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 0a  ers {F10020}.**.
0dd0: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65  ** These feature
0de0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
0df0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0e00: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
0e10: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53  RSION].** and [S
0e20: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0e30: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69  MBER] #defines i
0e40: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75  n the header, bu
0e50: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
0e60: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62  .** with the lib
0e70: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
0e80: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
0e90: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72    Cautious progr
0ea0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20  ammers might.** 
0eb0: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20  include a check 
0ec0: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
0ed0: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74  tion to verify t
0ee0: 68 61 74 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  hat .** sqlite3_
0ef0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f00: 72 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72  r() always retur
0f10: 6e 73 20 74 68 65 20 76 61 6c 75 65 20 0a 2a 2a  ns the value .**
0f20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0f30: 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  _NUMBER]..**.** 
0f40: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
0f50: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
0f60: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  n returns the sa
0f70: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0f80: 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  s is.** in the s
0f90: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
0fa0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
0fb0: 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
0fc0: 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  is provided.** f
0fd0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
0fe0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
0ff0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1000: 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ve direct access
1010: 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f   to string.** co
1020: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1030: 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  he DLL..**.** IN
1040: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1050: 7b 46 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71  {F10021} The [sq
1060: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1070: 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72  _number()] inter
1080: 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 6e 20  face returns an 
1090: 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
10a0: 20 20 20 20 65 71 75 61 6c 20 74 6f 20 5b 53 51      equal to [SQ
10b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
10c0: 42 45 52 5d 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31  BER]. .**.** {F1
10d0: 30 30 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  0022} The [sqlit
10e0: 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69  e3_version] stri
10f0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74  ng constant cont
1100: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66  ains the text of
1110: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1120: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1130: 5d 20 73 74 72 69 6e 67 2e 20 0a 2a 2a 0a 2a 2a  ] string. .**.**
1140: 20 7b 46 31 30 30 32 33 7d 20 54 68 65 20 5b 73   {F10023} The [s
1150: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1160: 6e 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  n()] function re
1170: 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1180: 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74    a pointer to t
1190: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73  he [sqlite3_vers
11a0: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  ion] string cons
11b0: 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tant..*/.SQLITE_
11c0: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
11d0: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
11e0: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
11f0: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1200: 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ion(void);.int s
1210: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1220: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1230: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1240: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
1250: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
1260: 68 72 65 61 64 73 61 66 65 20 7b 46 31 30 31 30  hreadsafe {F1010
1270: 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
1280: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
1290: 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20  with or without 
12a0: 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a  mutexes.  When.*
12b0: 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52  * the SQLITE_THR
12c0: 45 41 44 53 41 46 45 20 43 20 70 72 65 70 72 6f  EADSAFE C prepro
12d0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
12e0: 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  true, mutexes.**
12f0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
1300: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
1310: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 61  dsafe.  When tha
1320: 74 20 6d 61 63 72 6f 20 6f 73 20 66 61 6c 73 65  t macro os false
1330: 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  ,.** the mutexes
1340: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1350: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1360: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1370: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1380: 69 74 65 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  ite from more th
1390: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
13a0: 2a 0a 2a 2a 20 54 68 65 72 65 20 69 73 20 61 20  *.** There is a 
13b0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
13c0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 20 66  rmance penalty f
13d0: 6f 72 20 65 6e 61 62 6c 69 6e 67 20 6d 75 74 65  or enabling mute
13e0: 78 65 73 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  xes..** So if sp
13f0: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1400: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1410: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1420: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1430: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1440: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1450: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1460: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
1470: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1480: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
1490: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
14a0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
14b0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
14c0: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
14d0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
14e0: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
14f0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1500: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1510: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
1520: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
1530: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
1540: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45   the SQLITE_THRE
1550: 41 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a  ADSAFE macro..**
1560: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1570: 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54  **.** {F10101} T
1580: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
1590: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
15a0: 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65  on returns nonze
15b0: 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  ro if.**        
15c0: 20 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d    SQLite was com
15d0: 70 69 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d  piled with its m
15e0: 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f  utexes enabled o
15f0: 72 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20  r zero.**       
1600: 20 20 20 69 66 20 53 51 4c 69 74 65 20 77 61 73     if SQLite was
1610: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1620: 75 74 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e  utexes disabled.
1630: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1640: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
1650: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1660: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
1670: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46  ection Handle {F
1680: 31 32 30 30 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  12000}.**.** Eac
1690: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
16a0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
16b0: 65 6e 74 65 64 20 62 79 20 70 6f 69 6e 74 65 72  ented by pointer
16c0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
16d0: 6f 66 20 74 68 65 0a 2a 2a 20 6f 70 61 71 75 65  of the.** opaque
16e0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
16f0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
1700: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
1710: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
1720: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
1730: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
1740: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1750: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1760: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1770: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1780: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
1790: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 0a  ts constructors.
17a0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
17b0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 74 73 20  close()] is its 
17c0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
17d0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
17e0: 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
17f0: 28 73 75 63 68 20 61 73 20 5b 73 71 6c 69 74 65  (such as [sqlite
1800: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1810: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1820: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
1830: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
1840: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
1850: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
1860: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
1870: 73 20 6f 6e 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  s on this.** obj
1880: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1890: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
18a0: 71 6c 69 74 65 33 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  qlite3;.../*.** 
18b0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
18c0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
18d0: 46 31 30 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 42 65  F10200}.**.** Be
18e0: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
18f0: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1900: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1910: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1920: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1930: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1940: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1950: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1960: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1970: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1980: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1990: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
19a0: 66 65 72 72 65 64 20 74 79 70 65 0a 2a 2a 20 64  ferred type.** d
19b0: 65 66 69 6e 69 74 69 6f 6e 73 2e 20 20 54 68 65  efinitions.  The
19c0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
19d0: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
19e0: 74 79 70 65 73 20 61 72 65 0a 2a 2a 20 73 75 70  types are.** sup
19f0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
1a00: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1a10: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  ty only..**.** I
1a20: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1a30: 20 7b 46 31 30 32 30 31 7d 20 54 68 65 20 5b 73   {F10201} The [s
1a40: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64  qlite_int64] and
1a50: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
1a60: 20 74 79 70 65 73 20 73 70 65 63 69 66 79 20 61   types specify a
1a70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 36 34 2d  .**          64-
1a80: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
1a90: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30  er..**.** {F1020
1aa0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75  2} The [sqlite_u
1ab0: 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69  int64] and [sqli
1ac0: 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65  te3_uint64] type
1ad0: 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20  s specify.**    
1ae0: 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20 75        a 64-bit u
1af0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
1b00: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
1b10: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
1b20: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
1b30: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
1b40: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1b50: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
1b60: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1b70: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
1b80: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1b90: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
1ba0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
1bb0: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
1bc0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
1bd0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
1be0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1bf0: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
1c00: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
1c10: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
1c20: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
1c30: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
1c40: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
1c50: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
1c60: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1c70: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
1c80: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
1c90: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
1ca0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
1cb0: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
1cc0: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
1cd0: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
1ce0: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
1cf0: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
1d00: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
1d10: 6e 74 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  nt.*/.#ifdef SQL
1d20: 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e  ITE_OMIT_FLOATIN
1d30: 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65  G_POINT.# define
1d40: 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
1d50: 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a  int64.#endif../*
1d60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
1d70: 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65  osing A Database
1d80: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32   Connection {F12
1d90: 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  010}.**.** This 
1da0: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
1db0: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
1dc0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1dd0: 63 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ct.  .**.** Appl
1de0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
1df0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1e00: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
1e10: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  l.** [sqlite3_st
1e20: 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74  mt | prepared st
1e30: 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 0a 2a 2a  atements] and.**
1e40: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
1e50: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c  lose | close] al
1e60: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  l [sqlite3_blob 
1e70: 7c 20 42 4c 4f 42 73 5d 20 0a 2a 2a 20 61 73 73  | BLOBs] .** ass
1e80: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1e90: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1ea0: 74 20 70 72 69 6f 72 0a 2a 2a 20 74 6f 20 61 74  t prior.** to at
1eb0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
1ec0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  e the [sqlite3] 
1ed0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 3c 74  object..**.** <t
1ee0: 6f 64 6f 3e 57 68 61 74 20 68 61 70 70 65 6e 73  odo>What happens
1ef0: 20 74 6f 20 70 65 6e 64 69 6e 67 20 74 72 61 6e   to pending tran
1f00: 73 61 63 74 69 6f 6e 73 3f 20 20 41 72 65 20 74  sactions?  Are t
1f10: 68 65 79 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  hey.** rolled ba
1f20: 63 6b 2c 20 6f 72 20 61 62 61 6e 64 6f 6e 65 64  ck, or abandoned
1f30: 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49  ?</todo>.**.** I
1f40: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1f50: 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20 5b 73   {F12011} The [s
1f60: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1f70: 69 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f  interface destro
1f80: 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  ys an [sqlite3] 
1f90: 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20  object.**       
1fa0: 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20     allocated by 
1fb0: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
1fc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1fd0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1fe0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1ff0: 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  , or [sqlite3_op
2000: 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  en_v2()]..**.** 
2010: 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b 73 71  {F12012} The [sq
2020: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 66  lite3_close()] f
2030: 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73 65 73  unction releases
2040: 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73 65 64   all memory used
2050: 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
2060: 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61      connection a
2070: 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20 6f 70  nd closes all op
2080: 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  en files..**.** 
2090: 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68 65 20  {F12013} If the 
20a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20b0: 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ion contains.** 
20c0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20d0: 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
20e0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 74 68  d statements] th
20f0: 61 74 20 68 61 76 65 20 6e 6f 74 20 62 65 65 6e  at have not been
2100: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6e  .**          fin
2110: 61 6c 69 7a 65 64 20 62 79 20 5b 73 71 6c 69 74  alized by [sqlit
2120: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 20  e3_finalize()], 
2130: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c  then [sqlite3_cl
2140: 6f 73 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ose()].**       
2150: 20 20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49     returns [SQLI
2160: 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 6c 65 61  TE_BUSY] and lea
2170: 76 65 73 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ves the connecti
2180: 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  on open..**.** {
2190: 46 31 32 30 31 34 7d 20 47 69 76 69 6e 67 20 73  F12014} Giving s
21a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
21b0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
21c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
21d0: 70 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  p..**.** LIMITAT
21e0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
21f0: 30 31 35 7d 20 54 68 65 20 70 61 72 61 6d 65 74  015} The paramet
2200: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2210: 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lose()] must be 
2220: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2230: 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ect.**          
2240: 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
2250: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
2260: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2270: 5d 20 6f 72 20 74 68 65 20 0a 2a 2a 20 20 20 20  ] or the .**    
2280: 20 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74        equivalent
2290: 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
22a0: 20 7b 55 31 32 30 31 35 7d 20 54 68 65 20 70 61   {U12015} The pa
22b0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
22c0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73  te3_close()] mus
22d0: 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
22e0: 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
22f0: 20 20 20 20 20 20 20 63 6c 6f 73 65 64 2e 0a 2a         closed..*
2300: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2310: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
2320: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
2330: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
2340: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
2350: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
2360: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
2370: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
2380: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
2390: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
23a0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
23b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
23c0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
23d0: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
23e0: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
23f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2400: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
2410: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
2420: 61 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a 2a 0a  ace {F12100}.**.
2430: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2440: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
2450: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20  is a convenient 
2460: 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 0a 2a  way of running.*
2470: 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 53 51  * one or more SQ
2480: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74  L statements wit
2490: 68 6f 75 74 20 61 20 6c 6f 74 20 6f 66 20 43 20  hout a lot of C 
24a0: 63 6f 64 65 2e 20 20 54 68 65 0a 2a 2a 20 53 51  code.  The.** SQ
24b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
24c0: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
24d0: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
24e0: 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
24f0: 5f 65 78 65 63 28 29 2e 20 20 54 68 65 20 73 74  _exec().  The st
2500: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
2510: 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e  luated one by on
2520: 65 0a 2a 2a 20 75 6e 74 69 6c 20 65 69 74 68 65  e.** until eithe
2530: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  r an error or an
2540: 20 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e   interrupt is en
2550: 63 6f 75 6e 74 65 72 65 64 20 6f 72 0a 2a 2a 20  countered or.** 
2560: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61  until they are a
2570: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72  ll done.  The 3r
2580: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
2590: 6e 20 6f 70 74 69 6f 6e 61 6c 0a 2a 2a 20 63 61  n optional.** ca
25a0: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69  llback that is i
25b0: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
25c0: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20  each row of any 
25d0: 71 75 65 72 79 20 72 65 73 75 6c 74 73 0a 2a 2a  query results.**
25e0: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65   produced by the
25f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
2600: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
2610: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a  ter tells where.
2620: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20  ** to write any 
2630: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a  error messages..
2640: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2650: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
2660: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
2670: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
2680: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2690: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
26a0: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
26b0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26c0: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
26d0: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
26e0: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
26f0: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
2700: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
2710: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2720: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2730: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2740: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
2750: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2760: 63 28 29 20 69 73 20 6a 75 73 74 20 61 20 63 6f  c() is just a co
2770: 6e 76 65 6e 69 65 6e 74 20 77 72 61 70 70 65 72  nvenient wrapper
2780: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2790: 54 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 31  TS:.** .** {F121
27a0: 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
27b0: 5f 65 78 65 63 28 29 5d 20 69 6e 74 65 72 66 61  _exec()] interfa
27c0: 63 65 20 65 76 61 6c 75 61 74 65 73 20 7a 65 72  ce evaluates zer
27d0: 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 0a  o or more UTF-8.
27e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f  **          enco
27f0: 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ded, semicolon-s
2800: 65 70 61 72 61 74 65 64 2c 20 53 51 4c 20 73 74  eparated, SQL st
2810: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 0a  atements in the.
2820: 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2830: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
2840: 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
2850: 72 61 6d 65 74 65 72 20 77 69 74 68 69 6e 20 74  rameter within t
2860: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
2870: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 73  ontext of the [s
2880: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 67  qlite3] object g
2890: 69 76 65 6e 20 69 6e 20 74 68 65 20 31 73 74 20  iven in the 1st 
28a0: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28b0: 20 7b 46 31 32 31 30 34 7d 20 54 68 65 20 72 65   {F12104} The re
28c0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
28d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
28e0: 73 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  s SQLITE_OK if a
28f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
2900: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
2910: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a  n successfully..
2920: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35 7d 20 54  **.** {F12105} T
2930: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2940: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
2950: 28 29 5d 20 69 73 20 61 6e 20 61 70 70 72 6f 70  ()] is an approp
2960: 72 69 61 74 65 20 0a 2a 2a 20 20 20 20 20 20 20  riate .**       
2970: 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 65 72 72 6f     non-zero erro
2980: 72 20 63 6f 64 65 20 69 66 20 61 6e 79 20 53 51  r code if any SQ
2990: 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  L statement fail
29a0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37  s..**.** {F12107
29b0: 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  } If one or more
29c0: 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
29d0: 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f  ements handed to
29e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
29f0: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2a00: 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64  turn results and
2a10: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2a20: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
2a30: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
2a40: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
2a50: 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  nction specified
2a60: 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
2a70: 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
2a80: 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63       invoked onc
2a90: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2aa0: 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20  f result..**.** 
2ab0: 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68 65 20  {F12110} If the 
2ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
2ad0: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75   a non-zero valu
2ae0: 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e then [sqlite3_
2af0: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
2b00: 20 20 20 20 77 69 6c 6c 20 61 62 6f 72 74 65 64      will aborted
2b10: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2b20: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74  nt it is current
2b30: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a  ly evaluating,.*
2b40: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20  *          skip 
2b50: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
2b60: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  QL statements, a
2b70: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
2b80: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 20 20 20  E_ABORT]..**    
2b90: 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74        <todo>What
2ba0: 20 68 61 70 70 65 6e 73 20 74 6f 20 2a 65 72 72   happens to *err
2bb0: 6d 73 67 20 68 65 72 65 3f 20 20 44 6f 65 73 20  msg here?  Does 
2bc0: 74 68 65 20 72 65 73 75 6c 74 20 63 6f 64 65 20  the result code 
2bd0: 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2be0: 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2bf0: 29 20 67 65 74 20 73 65 74 3f 3c 2f 74 6f 64 6f  ) get set?</todo
2c00: 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 33 7d  >.**.** {F12113}
2c10: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2c20: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 77 69  ec()] routine wi
2c30: 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20  ll pass its 4th 
2c40: 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67  parameter throug
2c50: 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  h.**          as
2c60: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
2c70: 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  er of the callba
2c80: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31  ck..**.** {F1211
2c90: 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2ca0: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
2cb0: 73 65 74 73 20 74 68 65 20 32 6e 64 20 70 61 72  sets the 2nd par
2cc0: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
2cd0: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
2ce0: 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d  ck to be the num
2cf0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2d00: 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2d10: 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  w of.**         
2d20: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
2d30: 46 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c  F12119} The [sql
2d40: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
2d50: 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 33 72  tine sets the 3r
2d60: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
2d70: 74 73 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts .**          
2d80: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
2d90: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2da0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
2db0: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
2dc0: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
2dd0: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
2de0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
2df0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
2e00: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
2e10: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2e20: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2e30: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 32 7d  ..**.** {F12122}
2e40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
2e50: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65  ec()] routine se
2e60: 74 73 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  ts the 4th param
2e70: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
2e80: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
2e90: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20   to be an array 
2ea0: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
2eb0: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74  trings holding t
2ec0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2ed0: 61 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63  ames of result c
2ee0: 6f 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e  olumns as obtain
2ef0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2f00: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
2f10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32 35 7d 20  .**.** {F12125} 
2f20: 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2f30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2f40: 5f 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c  _exec()] is NULL
2f50: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2f60: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28    [sqlite3_exec(
2f70: 29 5d 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 73  )] never invokes
2f80: 20 61 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6c   a callback.  Al
2f90: 6c 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 20  l query.**      
2fa0: 20 20 20 20 72 65 73 75 6c 74 73 20 61 72 65 20      results are 
2fb0: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64  silently discard
2fc0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 32  ed..**.** {F1212
2fd0: 38 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  8} If an error o
2fe0: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
2ff0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
3000: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
3010: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
3020: 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74  tements handed t
3030: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3040: 29 5d 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  )] then [sqlite3
3050: 5f 65 78 65 63 28 29 5d 20 77 69 6c 6c 0a 2a 2a  _exec()] will.**
3060: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
3070: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   an [SQLITE_ERRO
3080: 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  R | error code] 
3090: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
30a0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK]..**.** {F
30b0: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72  12131} If an err
30c0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
30d0: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75  parsing or evalu
30e0: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65  ating any of the
30f0: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
3100: 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69   handed to [sqli
3110: 74 65 33 5f 65 78 65 63 28 29 5d 20 61 6e 64 20  te3_exec()] and 
3120: 69 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  if the 5th param
3130: 65 74 65 72 20 28 65 72 72 6d 73 67 29 0a 2a 2a  eter (errmsg).**
3140: 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
3150: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3160: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
3170: 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
3180: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
3190: 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
31a0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 6f  the equivalent o
31b0: 66 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  f [sqlite3_mprin
31c0: 74 66 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  tf()] and.**    
31d0: 20 20 20 20 20 20 2a 65 72 72 6d 73 67 20 69 73        *errmsg is
31e0: 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
31f0: 6f 20 74 68 61 74 20 6d 65 73 73 61 67 65 2e 0a  o that message..
3200: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20 54  **.** {F12134} T
3210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3220: 28 29 5d 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  ()] routine does
3230: 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
3240: 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20  value of.**     
3250: 20 20 20 20 20 2a 65 72 72 6d 73 67 20 69 66 20       *errmsg if 
3260: 65 72 72 6d 73 67 20 69 73 20 4e 55 4c 4c 20 6f  errmsg is NULL o
3270: 72 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  r if there are n
3280: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3290: 7b 46 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71  {F12137} The [sq
32a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 66 75  lite3_exec()] fu
32b0: 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
32c0: 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
32d0: 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
32e0: 20 20 20 61 63 63 65 73 73 69 62 6c 65 20 76 69     accessible vi
32f0: 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
3300: 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
3310: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
3320: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
3330: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20  .**.** {U12141} 
3340: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
3350: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3360: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
3370: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
3380: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
3390: 71 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73  qlite3 | databas
33a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
33b0: 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54 68  *.** {U12142} Th
33c0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
33d0: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62  ction must not b
33e0: 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a  e closed while.*
33f0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3400: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3410: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 0a 2a 2a 20 7b  unning..** .** {
3420: 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c  U12143} The call
3430: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
3440: 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69  should use [sqli
3450: 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66  te3_free()] to f
3460: 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ree.**          
3470: 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
3480: 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20  *errmsg is left 
3490: 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65  pointing at once
34a0: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20   the error.**   
34b0: 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 20 69         message i
34c0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
34d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34  ed..**.** {U1214
34e0: 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74 65  5} The SQL state
34f0: 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65  ment text in the
3500: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3510: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3520: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  )].**          m
3530: 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ust remain uncha
3540: 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69  nged while [sqli
3550: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3560: 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
3570: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3580: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
3590: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
35b0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
35c0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
35d0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
35e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35f0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3600: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
3610: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
3620: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
3630: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
3640: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
3650: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
3660: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3670: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
3680: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
3690: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
36a0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
36b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c0: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
36d0: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
36e0: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
36f0: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
3700: 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b  es {F10210}.** K
3710: 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
3720: 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  OK.**.** Many SQ
3730: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3740: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3750: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3760: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3770: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3780: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3790: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
37a0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37b0: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
37c0: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
37d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f  result codes].*/
37e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37f0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
3800: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
3810: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
3820: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
3830: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
3840: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
3850: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
3860: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
3870: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
3880: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3890: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
38a0: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
38b0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
38c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38d0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
38e0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
38f0: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
3900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3910: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
3920: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
3930: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
3940: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
3950: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
3960: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
3970: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
3980: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3990: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
39a0: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
39b0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
39c0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
39d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
39e0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
39f0: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
3a00: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
3a10: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
3a20: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
3a30: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
3a40: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
3a50: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3a60: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
3a70: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
3a80: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
3a90: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
3aa0: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
3ab0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
3ac0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
3ad0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
3ae0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
3af0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b00: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
3b10: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
3b20: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
3b30: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
3b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
3b50: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
3b60: 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65   NOT USED. Table
3b70: 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66   or record not f
3b80: 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ound */.#define 
3b90: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
3ba0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
3bb0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
3bc0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
3bd0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
3be0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
3bf0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
3c00: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
3c10: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
3c20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
3c30: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
3c40: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61  * NOT USED. Data
3c50: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
3c60: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
3c70: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
3c80: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
3c90: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
3ca0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3cb0: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
3cc0: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
3cd0: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
3ce0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3cf0: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
3d00: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
3d10: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
3d20: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
3d30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
3d40: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
3d50: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
3d60: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
3d70: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
3d80: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
3d90: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
3da0: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
3db0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
3dc0: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
3dd0: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
3de0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
3df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
3e00: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
3e10: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
3e20: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
3e30: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
3e40: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
3e50: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
3e60: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
3e70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
3e80: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
3e90: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
3ea0: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
3eb0: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
3ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
3ed0: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
3ee0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3ef0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
3f00: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
3f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
3f20: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
3f30: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
3f40: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
3f50: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
3f60: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
3f70: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
3f80: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
3f90: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
3fa0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
3fb0: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
3fc0: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
3fd0: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
3fe0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
3ff0: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4000: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4010: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4020: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4030: 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 0a 2a 2a  s {F10220}.**.**
4040: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
4050: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
4060: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
4070: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
4080: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
4090: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
40a0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
40b0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
40c0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a  has shown that.*
40d0: 2a 20 6d 61 6e 79 20 6f 66 20 74 68 65 73 65 20  * many of these 
40e0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
40f0: 20 74 6f 6f 20 63 6f 75 72 73 65 2d 67 72 61 69   too course-grai
4100: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4110: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4120: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4130: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4140: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4150: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4160: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4170: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4180: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4190: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
41a0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
41b0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
41c0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
41d0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
41e0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
41f0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4200: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4210: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e  rrors. The exten
4220: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4230: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
4240: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66 6f 72 20  disabled.** for 
4250: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
4260: 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74  nnection using t
4270: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  he [sqlite3_exte
4280: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4290: 73 28 29 5d 0a 2a 2a 20 41 50 49 2e 0a 2a 2a 20  s()].** API..** 
42a0: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
42b0: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
42c0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
42d0: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
42e0: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
42f0: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
4300: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4310: 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65   codes will be e
4320: 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69  xpand.** over ti
4330: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4340: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4350: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4360: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4370: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4380: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4390: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
43a0: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
43b0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
43c0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
43d0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
43e0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
43f0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4400: 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  .** .** INVARIAN
4410: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32  TS:.**.** {F1022
4420: 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20  3} The symbolic 
4430: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65  name for an exte
4440: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4450: 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73   always contains
4460: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
4470: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72  elated primary r
4480: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20  esult code as a 
4490: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46  prefix..**.** {F
44a0: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72  10224} Primary r
44b0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
44c0: 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c   contain a singl
44d0: 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 2e  e "_" character.
44e0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20  .**.** {F10225} 
44f0: 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  Extended result 
4500: 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61  code names conta
4510: 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22  in two or more "
4520: 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  _" characters..*
4530: 2a 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20 54 68  *.** {F10226} Th
4540: 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  e numeric value 
4550: 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  of an extended r
4560: 65 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61  esult code conta
4570: 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
4580: 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75      numeric valu
4590: 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70  e of its corresp
45a0: 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72  onding primary r
45b0: 65 73 75 6c 74 20 63 6f 64 65 20 69 74 0a 2a 2a  esult code it.**
45c0: 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c 65            its le
45d0: 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20  ast significant 
45e0: 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69  8 bits..*/.#defi
45f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4600: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 28 53  READ          (S
4610: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4630: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4640: 5f 52 45 41 44 20 20 20 20 28 53 51 4c 49 54 45  _READ    (SQLITE
4650: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
4660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4670: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
4680: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4690: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
46a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
46b0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
46c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
46d0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
46e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
46f0: 46 53 59 4e 43 20 20 20 20 20 28 53 51 4c 49 54  FSYNC     (SQLIT
4700: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4710: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4720: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4730: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4740: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
4750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4760: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
4770: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4780: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
4790: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
47a0: 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  OCK        (SQLI
47b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
47c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
47d0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
47e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
47f0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4810: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4820: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4830: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
4840: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
4850: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 28 53 51  LOCKED       (SQ
4860: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
4870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4880: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
4890: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
48a0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
48b0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
48c0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
48d0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
48e0: 73 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a  s {F10230}.**.**
48f0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
4900: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
4910: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 6e 0a 2a  or use in then.*
4920: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
4930: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
4940: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
4950: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
4960: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
4970: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
4980: 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  thod of the.** [
4990: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
49a0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
49b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
49c0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
49d0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
49e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
49f0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
4a00: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
4a10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
4a20: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
4a30: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
4a40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
4a50: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
4a60: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
4a70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
4a80: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
4a90: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
4aa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
4ab0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
4ac0: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
4ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
4ae0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
4af0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
4b00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
4b10: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
4b20: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
4b30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
4b40: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
4b50: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
4b60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
4b70: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
4b80: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
4b90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
4ba0: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
4bb0: 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20  0002000.#define 
4bc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
4bd0: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
4be0: 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0004000../*.** C
4bf0: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
4c00: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
4c10: 7b 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F10240}.**.** T
4c20: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
4c30: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
4c40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
4c50: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
4c60: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
4c70: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
4c80: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
4c90: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
4ca0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
4cb0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
4cc0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
4cd0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
4ce0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
4cf0: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
4d00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
4d10: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
4d20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
4d30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
4d40: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
4d50: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
4d60: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
4d70: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
4d80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
4d90: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
4da0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
4db0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
4dc0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
4dd0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
4de0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
4df0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
4e00: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
4e10: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
4e20: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
4e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
4e40: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
4e50: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
4e60: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
4e70: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
4e80: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
4e90: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
4ea0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
4eb0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
4ec0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
4ed0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
4ee0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
4ef0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
4f00: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
4f10: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
4f20: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
4f30: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
4f40: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
4f50: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
4f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
4f80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
4f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fa0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
4fb0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
4fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
4fe0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5010: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5030: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5040: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5060: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5070: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5090: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
50a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
50d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
50e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5100: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5120: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5130: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
5140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5150: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5160: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5170: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5180: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
5190: 65 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a 2a  evels {F10250}.*
51a0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
51b0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
51c0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
51d0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
51e0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
51f0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
5200: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5210: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
5220: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5230: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5240: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
5250: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
5260: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
5280: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
52a0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
52b0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
52c0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
52d0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
52e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
52f0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
5300: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
5310: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
5320: 20 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d 0a   Flags {F10260}.
5330: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
5340: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
5350: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
5360: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
5370: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5380: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
5390: 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ination of the.*
53a0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
53b0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
53c0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
53d0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
53e0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
53f0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
5400: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
5410: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
5420: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
5430: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
5440: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
5450: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
5460: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
5470: 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51   flushed. The SQ
5480: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5490: 20 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73   means .** to us
54a0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
54b0: 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65 20   semantics. The 
54c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
54d0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20   flag means .** 
54e0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20  to use Mac OS-X 
54f0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5500: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5510: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5520: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5530: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5550: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5560: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5570: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5580: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5590: 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  010.../*.** CAPI
55a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
55b0: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
55c0: 64 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a  dle {F11110}.**.
55d0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
55e0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
55f0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5600: 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a  ile in the OS.**
5610: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5620: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
5630: 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65   interface imple
5640: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
5650: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
5660: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
5670: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
5680: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
5690: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
56a0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
56b0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
56c0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
56d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
56e0: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
56f0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
5700: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
5710: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
5720: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
5730: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
5740: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
5750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
5760: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
5770: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
5780: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
5790: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
57a0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
57b0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
57c0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
57d0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
57e0: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
57f0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20   Methods Object 
5800: 7b 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45  {F11120}.**.** E
5810: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
5820: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
5830: 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68  _vfs] xOpen meth
5840: 6f 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f  od contains a po
5850: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69  inter to.** an i
5860: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74  nstance of the t
5870: 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  his object.  Thi
5880: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
5890: 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20   the.** methods 
58a0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
58b0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
58c0: 6e 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ns against the o
58d0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  pen file..**.** 
58e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
58f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
5900: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
5910: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
5920: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
5930: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
5940: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
5950: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
5960: 2e 0a 2a 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ..*  The second 
5970: 63 68 6f 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20  choice is an.** 
5980: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
5990: 79 6e 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ync.  The SQLITE
59a0: 5f 53 59 4e 43 5f 44 41 54 41 20 66 6c 61 67 20  _SYNC_DATA flag 
59b0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
59c0: 6f 0a 2a 2a 20 69 6e 64 69 63 61 74 65 20 74 68  o.** indicate th
59d0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
59e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 61 6e 64   of the file and
59f0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
5a00: 65 65 64 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79  eeds to be.** sy
5a10: 6e 63 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65  nced..** .** The
5a20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
5a30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
5a40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
5a50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
5a60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
5a70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
5a80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
5a90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
5aa0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
5ab0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
5ac0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
5ad0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
5ae0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
5af0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
5b00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
5b10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
5b20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
5b30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ases the lock.  
5b40: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
5b50: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
5b60: 68 6f 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20  hod looks.** to 
5b70: 73 65 65 20 69 66 20 61 6e 79 20 64 61 74 61 62  see if any datab
5b80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
5b90: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 0a 2a  either in this.*
5ba0: 2a 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  * process or in 
5bb0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
5bc0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
5bd0: 6e 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  n RESERVED,.** P
5be0: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
5bf0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
5c00: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
5c10: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
5c20: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
5c30: 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 6e 6f   and false if no
5c40: 74 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46  t..** .** The xF
5c50: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
5c60: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
5c70: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
5c80: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
5c90: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
5ca0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
5cb0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
5cc0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
5cd0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
5ce0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
5cf0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
5d00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
5d10: 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
5d20: 72 20 6f 70 63 6f 64 65 2e 20 20 20 54 68 65 20  r opcode.   The 
5d30: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
5d40: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
5d50: 6f 69 6e 74 65 72 20 77 68 69 63 68 20 69 73 20  ointer which is 
5d60: 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
5d70: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
5d80: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
5d90: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
5da0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
5db0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
5dc0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
5dd0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
5de0: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
5df0: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
5e00: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
5e10: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
5e20: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
5e30: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
5e40: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
5e50: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
5e60: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
5e70: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
5e80: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
5e90: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
5ea0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
5eb0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
5ec0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
5ed0: 65 20 72 65 73 65 72 76 65 73 20 6f 70 63 6f 64  e reserves opcod
5ee0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
5ef0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
5f00: 2e 20 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  . .** A [SQLITE_
5f10: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
5f20: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
5f30: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
5f40: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
5f50: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
5f60: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
5f70: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
5f80: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
5f90: 73 65 20 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67  se opcodes .** g
5fa0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
5fb0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
5fc0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ts..**.** The xS
5fd0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
5fe0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
5ff0: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
6000: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6010: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
6020: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
6030: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
6040: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
6050: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
6060: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
6070: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
6080: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
6090: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
60a0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
60b0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
60c0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
60d0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
60e0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
60f0: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
6100: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
6110: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6120: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
6130: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6140: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
6150: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6160: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
6170: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6180: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
6190: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
61a0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
61b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
61c0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
61d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
61e0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
61f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6200: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
6210: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6220: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
6230: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6240: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6250: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6260: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6270: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
6280: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
6290: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
62a0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
62b0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
62c0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
62d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
62e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
62f0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
6300: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
6310: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
6320: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
6330: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
6340: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
6350: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
6360: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
6370: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
6380: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6390: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
63a0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
63b0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
63c0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
63d0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
63e0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
63f0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
6400: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
6410: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
6420: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
6430: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
6440: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6450: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
6460: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6470: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
6480: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
6490: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
64a0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
64b0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70  xWrite()..*/.typ
64c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
64d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
64e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
64f0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
6500: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
6510: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
6520: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
6530: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
6540: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
6550: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
6560: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
6570: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
6580: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
6590: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
65a0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
65b0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
65c0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
65d0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
65e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
65f0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6600: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
6610: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
6620: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
6630: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
6640: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
6650: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
6660: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
6670: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
6680: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
6690: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
66a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
66b0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
66c0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
66d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
66e0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
66f0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
6700: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
6710: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
6720: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
6730: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
6740: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
6750: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
6760: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
6770: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
6780: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
6790: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
67a0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
67b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
67c0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
67d0: 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 46 31 31  rol Opcodes {F11
67e0: 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  310}.**.** These
67f0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6800: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
6810: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
6820: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
6830: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6840: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6850: 20 61 6e 64 20 74 6f 20 74 68 65 20 5b 73 71 6c   and to the [sql
6860: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6870: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
6880: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
6890: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
68a0: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
68b0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
68c0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
68d0: 6f 64 65 20 63 61 73 65 73 20 74 68 65 20 78 46  ode cases the xF
68e0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
68f0: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
6900: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
6910: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
6920: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
6930: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
6940: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6950: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
6960: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
6970: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6980: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
6990: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
69a0: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
69b0: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
69c0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
69d0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
69e0: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
69f0: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f  ng testing and o
6a00: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
6a10: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
6a20: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73  QLITE_TEST.** is
6a30: 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65   defined..*/.#de
6a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
6a50: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
6a60: 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     1../*.** CAPI
6a70: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
6a80: 6c 65 20 7b 46 31 37 31 31 30 7d 0a 2a 2a 0a 2a  le {F17110}.**.*
6a90: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
6aa0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
6ab0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
6ac0: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
6ad0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
6ae0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
6af0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
6b00: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
6b10: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
6b20: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
6b30: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
6b40: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
6b50: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
6b60: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
6b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
6b80: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
6b90: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
6ba0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
6bb0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
6bc0: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
6bd0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
6be0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
6bf0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
6c00: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
6c10: 65 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 34 30  e Object {F11140
6c20: 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
6c30: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
6c40: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
6c50: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
6c60: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 63   the.** SQLite c
6c70: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
6c80: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
6c90: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
6ca0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
6cb0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
6cc0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
6cd0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
6ce0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 56 65  "..**.** The iVe
6cf0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
6d00: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
6d10: 61 79 20 62 65 20 6c 61 72 67 65 72 20 66 6f 72  ay be larger for
6d20: 20 66 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   future.** versi
6d30: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
6d40: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
6d50: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
6d60: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
6d70: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
6d80: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
6d90: 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  ncreased..**.** 
6da0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
6db0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
6dc0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
6dd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
6de0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
6df0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
6e00: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
6e10: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
6e20: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
6e30: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
6e40: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
6e50: 76 66 73 20 6d 6f 64 75 6c 65 73 20 61 72 65 20  vfs modules are 
6e60: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
6e70: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
6e80: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
6e90: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
6ea0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
6eb0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
6ec0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
6ed0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
6ee0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
6ef0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
6f00: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
6f10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
6f20: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
6f30: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
6f40: 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ist..**.** The p
6f50: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
6f60: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 73 20 69 6e  e only fields in
6f70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
6f80: 20 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74   .** structure t
6f90: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
6fa0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
6fb0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
6fc0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
6fd0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
6fe0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
6ff0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
7000: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
7010: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
7020: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
7030: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
7040: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
7050: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
7060: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
7070: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
7080: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
7090: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
70a0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
70b0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
70c0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
70d0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
70e0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  modules..**.** {
70f0: 46 31 31 31 34 31 7d 20 53 51 4c 69 74 65 20 77  F11141} SQLite w
7100: 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68  ill guarantee th
7110: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
7120: 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20 74   string passed t
7130: 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73 20  o.** xOpen() is 
7140: 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20  a full pathname 
7150: 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  as generated by 
7160: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
7170: 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  and.** that the 
7180: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
7190: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
71a0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
71b0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
71c0: 20 7b 45 4e 44 7d 20 53 6f 20 74 68 65 20 5b 73   {END} So the [s
71d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
71e0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
71f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7200: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7210: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7220: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
7230: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  e reason..**.** 
7240: 7b 46 31 31 31 34 32 7d 20 54 68 65 20 66 6c 61  {F11142} The fla
7250: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7260: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
7270: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
7280: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
7290: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
72a0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
72b0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
72c0: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
72d0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
72e0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
72f0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
7300: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
7310: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
7320: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
7330: 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a  REATE]. {END}.**
7340: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
7350: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
7360: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
7370: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
7380: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
7390: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
73a0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
73b0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
73c0: 65 0a 2a 2a 20 73 65 74 2e 0a 2a 2a 20 0a 2a 2a  e.** set..** .**
73d0: 20 7b 46 31 31 31 34 33 7d 20 53 51 4c 69 74 65   {F11143} SQLite
73e0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
73f0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
7400: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7410: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
7420: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
7430: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
7440: 6f 70 65 6e 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c  opened:.** .** <
7450: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
7460: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
7470: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
7480: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
7490: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
74a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
74b0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
74c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
74d0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
74e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
74f0: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
7500: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
7510: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
7520: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7530: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
7540: 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b  RNAL].** </ul> {
7550: 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  END}.**.** The f
7560: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
7570: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
7580: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
7590: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
75a0: 65 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65  es the way it de
75b0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
75c0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
75d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
75e0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
75f0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
7600: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
7610: 61 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a  ack, might make.
7620: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
7630: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
7640: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
7650: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61  o this journal a
7660: 72 65 0a 2a 2a 20 61 6c 73 6f 20 61 20 6e 6f 2d  re.** also a no-
7670: 6f 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  op.  Any attempt
7680: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
7690: 72 6e 61 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  rnal return SQLI
76a0: 54 45 5f 49 4f 45 52 52 2e 0a 2a 2a 20 4f 72 20  TE_IOERR..** Or 
76b0: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
76c0: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
76d0: 7a 65 20 74 68 65 20 61 20 64 61 74 61 62 61 73  ze the a databas
76e0: 65 20 66 69 6c 65 20 77 69 6c 6c 0a 2a 2a 20 62  e file will.** b
76f0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
7700: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
7710: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
7720: 61 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72 0a 2a  a random order.*
7730: 2a 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  * and set up its
7740: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
7750: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 20 0a  ccordingly..** .
7760: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
7770: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
7780: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7790: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
77a0: 0a 2a 2a 20 6d 65 74 68 6f 64 3a 0a 2a 2a 20 0a  .** method:.** .
77b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
77c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
77d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
77e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
77f0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
7800: 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 31  /ul>.** .** {F11
7810: 31 34 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  145} The [SQLITE
7820: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
7830: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
7840: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
7850: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
7860: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
7870: 20 20 7b 46 31 31 31 34 36 7d 20 54 68 65 20 5b    {F11146} The [
7880: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
7890: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
78a0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
78b0: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
78c0: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
78d0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20 0a 2a 2a  subjournals. .**
78e0: 20 7b 46 31 31 31 34 37 7d 20 54 68 65 20 5b 53   {F11147} The [S
78f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7900: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  SIVE] flag means
7910: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
7920: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f   be opened.** fo
7930: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
7940: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69  ss.  This flag i
7950: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69  s set for all fi
7960: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f  les except.** fo
7970: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
7980: 61 73 65 20 66 69 6c 65 2e 20 7b 45 4e 44 7d 0a  ase file. {END}.
7990: 2a 2a 20 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20  ** .** {F11148} 
79a0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
79b0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
79c0: 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
79d0: 79 20 53 51 4c 69 74 65 20 0a 2a 2a 20 74 6f 20  y SQLite .** to 
79e0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
79f0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
7a00: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
7a10: 20 74 68 69 72 64 20 0a 2a 2a 20 61 72 67 75 6d   third .** argum
7a20: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 7b  ent to xOpen.  {
7a30: 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20  END}  The xOpen 
7a40: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
7a50: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
7a60: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
7a70: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
7a80: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a  t fill it in..**
7a90: 20 0a 2a 2a 20 7b 46 31 31 31 34 39 7d 20 54 68   .** {F11149} Th
7aa0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7ab0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
7ac0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
7ad0: 45 53 53 5f 45 58 49 53 54 53 5d 20 0a 2a 2a 20  ESS_EXISTS] .** 
7ae0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
7af0: 65 78 69 73 74 61 6e 63 65 20 6f 66 20 61 20 66  existance of a f
7b00: 69 6c 65 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  ile,.** or [SQLI
7b10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
7b20: 49 54 45 5d 20 74 6f 20 74 65 73 74 20 74 6f 20  ITE] to test to 
7b30: 73 65 65 0a 2a 2a 20 69 66 20 61 20 66 69 6c 65  see.** if a file
7b40: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
7b50: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
7b60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
7b70: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 74 6f  D].** to test to
7b80: 20 73 65 65 20 69 66 20 61 20 66 69 6c 65 20 69   see if a file i
7b90: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
7ba0: 62 6c 65 2e 20 20 7b 45 4e 44 7d 20 54 68 65 20  ble.  {END} The 
7bb0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 20 0a 2a  file can be a .*
7bc0: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  * directory..** 
7bd0: 0a 2a 2a 20 7b 46 31 31 31 35 30 7d 20 53 51 4c  .** {F11150} SQL
7be0: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
7bf0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
7c00: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
7c10: 79 74 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6f  yte for.** the o
7c20: 75 74 70 75 74 20 62 75 66 66 65 72 73 20 66 6f  utput buffers fo
7c30: 72 20 78 47 65 74 54 65 6d 70 6e 61 6d 65 20 61  r xGetTempname a
7c40: 6e 64 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  nd xFullPathname
7c50: 2e 20 7b 46 31 31 31 35 31 7d 20 54 68 65 20 65  . {F11151} The e
7c60: 78 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  xact.** size of 
7c70: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
7c80: 72 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  r is also passed
7c90: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
7ca0: 74 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65 74 68  to both .** meth
7cb0: 6f 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20 74 68  ods. {END} If th
7cc0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  e output buffer 
7cd0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
7ce0: 75 67 68 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54  ugh, SQLITE_CANT
7cf0: 4f 50 45 4e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  OPEN.** should b
7d00: 65 20 72 65 74 75 72 6e 65 64 2e 20 41 73 20 74  e returned. As t
7d10: 68 69 73 20 69 73 20 68 61 6e 64 6c 65 64 20 61  his is handled a
7d20: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
7d30: 62 79 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 76 66  by SQLite,.** vf
7d40: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
7d50: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
7d60: 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  r to prevent thi
7d70: 73 20 62 79 20 73 65 74 74 69 6e 67 20 0a 2a 2a  s by setting .**
7d80: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
7d90: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
7da0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a  rge value..** .*
7db0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
7dc0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
7dd0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
7de0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
7df0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
7e00: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
7e10: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
7e20: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
7e30: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
7e40: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
7e50: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
7e60: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
7e70: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
7e80: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
7e90: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
7ea0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
7eb0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
7ec0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
7ed0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
7ee0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
7ef0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
7f00: 73 73 20 6f 62 74 61 69 6e 65 64 2e 20 20 54 68  ss obtained.  Th
7f10: 65 0a 2a 2a 20 78 53 6c 65 65 70 28 29 20 6d 65  e.** xSleep() me
7f20: 74 68 6f 64 20 63 61 75 73 65 20 74 68 65 20 63  thod cause the c
7f30: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
7f40: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
7f50: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
7f60: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
7f70: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
7f80: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
7f90: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7fa0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
7fb0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
7fc0: 6e 74 20 64 61 74 65 20 61 6e 64 0a 2a 2a 20 74  nt date and.** t
7fd0: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ime..*/.typedef 
7fe0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
7ff0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
8000: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
8010: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
8020: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
8030: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
8040: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
8050: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
8060: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
8070: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
8080: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
8090: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
80a0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
80b0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
80c0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
80d0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
80e0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
80f0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
8100: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
8110: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
8120: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
8130: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
8140: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
8150: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
8160: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
8170: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
8180: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
8190: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
81a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
81b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
81c0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
81d0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
81e0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
81f0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
8200: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
8210: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8220: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
8230: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
8240: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
8250: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
8260: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
8270: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 54  );.  int (*xGetT
8280: 65 6d 70 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  empname)(sqlite3
8290: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c  _vfs*, int nOut,
82a0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
82b0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
82c0: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
82d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
82e0: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
82f0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
8300: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
8310: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8320: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
8330: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
8340: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
8350: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
8360: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
8370: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
8380: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
8390: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
83a0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
83b0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
83c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
83d0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
83e0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
83f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
8400: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
8410: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
8420: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8430: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
8440: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
8450: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
8460: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
8470: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  /* New fields
8480: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
8490: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
84a0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
84b0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
84c0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
84d0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
84e0: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ns. */.};../*.**
84f0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
8500: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
8510: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31   VFS method {F11
8520: 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  190}.**.** {F111
8530: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65  91} These intege
8540: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
8550: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
8560: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
8570: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
8580: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
8590: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
85a0: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
85b0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
85c0: 20 6b 69 6e 64 20 6f 66 20 77 68 61 74 20 6b 69   kind of what ki
85d0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
85e0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
85f0: 74 68 6f 64 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69  thod is.** looki
8600: 6e 67 20 66 6f 72 2e 20 20 7b 46 31 31 31 39 32  ng for.  {F11192
8610: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
8620: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
8630: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8640: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
8650: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66   to see if the f
8660: 69 6c 65 20 65 78 69 73 74 73 2e 20 7b 46 31 31  ile exists. {F11
8670: 31 39 33 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c  193} With.** SQL
8680: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
8690: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
86a0: 73 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  s method checks 
86b0: 74 6f 20 73 65 65 0a 2a 2a 20 69 66 20 74 68 65  to see.** if the
86c0: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65   file is both re
86d0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
86e0: 62 6c 65 2e 20 20 7b 46 31 31 31 39 34 7d 20 57  ble.  {F11194} W
86f0: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43  ith.** SQLITE_AC
8700: 43 45 53 53 5f 52 45 41 44 20 74 68 65 20 78 41  CESS_READ the xA
8710: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
8720: 63 68 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66  checks to see if
8730: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
8740: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
8750: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8760: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
8770: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8780: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
8790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
87a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
87b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
87c0: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
87d0: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
87e0: 6c 74 20 43 6f 64 65 73 20 7b 46 31 32 32 30 30  lt Codes {F12200
87f0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
8800: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
8810: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
8820: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
8830: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
8840: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
8850: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
8860: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
8870: 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  re of SQLite..**
8880: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
8890: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 64  sult codes are d
88a0: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
88b0: 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
88c0: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
88d0: 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ty..**.** INVARI
88e0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
88f0: 32 30 31 7d 20 4e 65 77 20 5b 73 71 6c 69 74 65  201} New [sqlite
8900: 33 20 7c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  3 | database con
8910: 6e 65 63 74 69 6f 6e 73 5d 20 68 61 76 65 20 74  nections] have t
8920: 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
8930: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
8940: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
8950: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
8960: 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ure.**          
8970: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
8980: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ult..**.** {F122
8990: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
89a0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
89b0: 5f 63 6f 64 65 73 28 29 5d 20 69 6e 74 65 72 66  _codes()] interf
89c0: 61 63 65 20 77 69 6c 6c 20 65 6e 61 62 6c 65 0a  ace will enable.
89d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
89e0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
89f0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
8a00: 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20   codes] for the 
8a10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
8a20: 6c 69 74 65 33 20 7c 20 64 61 74 61 62 61 73 65  lite3 | database
8a30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20   connection] in 
8a40: 69 74 73 20 31 73 74 20 70 61 72 61 6d 65 74 65  its 1st paramete
8a50: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  r.**          if
8a60: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
8a70: 65 72 20 69 74 20 74 72 75 65 2c 20 6f 72 20 64  er it true, or d
8a80: 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 74  isable them if t
8a90: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 32  he.**          2
8aa0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
8ab0: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
8ac0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
8ad0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
8ae0: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
8af0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8b00: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
8b10: 6f 77 69 64 20 7b 46 31 32 32 32 30 7d 0a 2a 2a  owid {F12220}.**
8b20: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
8b30: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
8b40: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
8b50: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
8b60: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
8b70: 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20  ed the "rowid". 
8b80: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
8b90: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
8ba0: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
8bb0: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
8bc0: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
8bd0: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
8be0: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
8bf0: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
8c00: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
8c10: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
8c20: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c  . If.** the tabl
8c30: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
8c40: 66 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50  f type INTEGER P
8c50: 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20  RIMARY KEY then 
8c60: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
8c70: 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c 69  s another an ali
8c80: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
8c90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
8ca0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
8cb0: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f   rowid of the mo
8cc0: 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
8cd0: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69  cessful INSERT i
8ce0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
8cf0: 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61   from the databa
8d00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
8d10: 20 73 68 6f 77 6e 20 69 6e 20 74 68 65 20 66 69   shown in the fi
8d20: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  rst argument.  I
8d30: 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
8d40: 69 6e 73 65 72 74 73 0a 2a 2a 20 68 61 76 65 20  inserts.** have 
8d50: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
8d60: 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
8d70: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
8d80: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
8d90: 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20  ** If an INSERT 
8da0: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
8db0: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
8dc0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 0a 2a  e rowid of the.*
8dd0: 2a 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 69  * inserted row i
8de0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
8df0: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
8e00: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
8e10: 72 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 2e  r.** is running.
8e20: 20 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74    But once the t
8e30: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
8e40: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
8e50: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  urned.** by this
8e60: 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
8e70: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
8e80: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
8e90: 72 65 20 74 68 65 0a 2a 2a 20 74 72 69 67 67 65  re the.** trigge
8ea0: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  r fired..**.** A
8eb0: 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61  n INSERT that fa
8ec0: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
8ed0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
8ee0: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
8ef0: 63 63 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20  ccessful insert 
8f00: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
8f10: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
8f20: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
8f30: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
8f40: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
8f50: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
8f60: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
8f70: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
8f80: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
8f90: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
8fa0: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
8fb0: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
8fc0: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
8fd0: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
8fe0: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
8ff0: 20 52 45 50 4c 41 43 45 20 0a 2a 2a 20 65 6e 63   REPLACE .** enc
9000: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
9010: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
9020: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
9030: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
9040: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
9050: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
9060: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
9070: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
9080: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
9090: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
90a0: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
90b0: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
90c0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
90d0: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
90e0: 2e 20 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65  . .**.** For the
90f0: 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
9100: 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 69 6e  s routine, an in
9110: 73 65 72 74 20 69 73 20 63 6f 6e 73 69 64 65 72  sert is consider
9120: 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
9130: 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
9140: 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
9150: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
9160: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
9170: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20  .**.** {F12221} 
9180: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
9190: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
91a0: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
91b0: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
91c0: 20 20 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20     rowid of the 
91d0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
91e0: 65 73 73 66 75 6c 20 69 6e 73 65 72 74 20 64 6f  essful insert do
91f0: 6e 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ne.**          o
9200: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
9210: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
9220: 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nd within the sa
9230: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  me.**          t
9240: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
9250: 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
9260: 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
9270: 20 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66    been no qualif
9280: 79 69 6e 67 20 69 6e 73 65 72 74 73 20 6f 6e 20  ying inserts on 
9290: 74 68 61 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  that connection.
92a0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20  .**.** {F12223} 
92b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
92c0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
92d0: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
92e0: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ns.**          s
92f0: 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63  ame value when c
9300: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
9310: 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74  ame trigger cont
9320: 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
9330: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9340: 72 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52  re and after a R
9350: 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 4c  OLLBACK..**.** L
9360: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
9370: 2a 20 7b 55 31 32 32 33 32 7d 20 49 66 20 73 65  * {U12232} If se
9380: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 64 6f  parate thread do
9390: 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74 20  es a new insert 
93a0: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
93b0: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
93c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
93d0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
93e0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
93f0: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
9400: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
9410: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
9420: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
9430: 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20  sert rowid,.**  
9440: 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
9450: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
9460: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
9470: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
9480: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
9490: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
94a0: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
94b0: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
94c0: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20   or the new.**  
94d0: 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73          last ins
94e0: 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71  ert rowid..*/.sq
94f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
9500: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
9510: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
9520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9530: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
9540: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
9550: 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a  ied {F12240}.**.
9560: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
9570: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
9580: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
9590: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
95a0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
95b0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
95c0: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
95d0: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
95e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
95f0: 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   on the connecti
9600: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
9610: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
9620: 74 65 72 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68  ter.  Only.** ch
9630: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
9640: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
9650: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
9660: 20 55 50 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44   UPDATE, or.** D
9670: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
9680: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
9690: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
96a0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
96b0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
96c0: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
96d0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
96e0: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
96f0: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
9700: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
9710: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
9720: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
9730: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
9740: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
9750: 67 65 73 22 20 69 73 20 61 20 63 68 61 6e 67 65  ges" is a change
9760: 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
9770: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
9780: 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
9790: 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
97a0: 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
97b0: 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
97c0: 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
97d0: 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
97e0: 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e  s of REPLACE con
97f0: 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
9800: 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
9810: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
9820: 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f  g, DROP TABLE, o
9830: 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
9840: 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
9850: 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
9860: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
9870: 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
9880: 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
9890: 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
98a0: 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
98b0: 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
98c0: 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
98d0: 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53  trigger.  Most S
98e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
98f0: 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
9900: 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
9910: 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
9920: 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
9930: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
9940: 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
9950: 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
9960: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
9970: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
9980: 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
9990: 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
99a0: 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
99b0: 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
99c0: 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
99d0: 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
99e0: 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
99f0: 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** Calling [sqli
9a00: 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
9a10: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
9a20: 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
9a30: 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
9a40: 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
9a50: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  text..**.** This
9a60: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
9a70: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
9a80: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
9a90: 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
9aa0: 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
9ab0: 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
9ac0: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
9ad0: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
9ae0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
9af0: 0a 2a 2a 0a 2a 2a 20 53 6f 20 77 68 65 6e 20 63  .**.** So when c
9b00: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
9b10: 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
9b20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
9b30: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
9b40: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
9b50: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
9b60: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
9b70: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
9b80: 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
9b90: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 0a 2a 2a  he top level..**
9ba0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
9bb0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 20 74   of a trigger, t
9bc0: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
9bd0: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  es() interface.*
9be0: 2a 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  * can be called 
9bf0: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
9c00: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
9c10: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
9c20: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
9c30: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
9c40: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
9c50: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
9c60: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
9c70: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
9c80: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
9c90: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
9ca0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 69 6e 20   not include in 
9cb0: 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
9cc0: 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
9cd0: 20 73 69 6e 63 65 20 74 68 65 79 20 68 61 76 65   since they have
9ce0: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
9cf0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
9d00: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
9d10: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
9d20: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
9d30: 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63  out.** a WHERE c
9d40: 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e  lause by droppin
9d50: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
9d60: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
9d70: 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61  is is much.** fa
9d80: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 20  ster than going 
9d90: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
9da0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
9db0: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
9dc0: 65 0a 2a 2a 20 74 61 62 6c 65 2e 29 20 20 42 65  e.** table.)  Be
9dd0: 63 61 75 73 65 20 6f 66 20 74 68 69 73 20 6f 70  cause of this op
9de0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
9df0: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  deletions in.** 
9e00: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
9e10: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20  le" are not row 
9e20: 63 68 61 6e 67 65 73 20 61 6e 64 20 77 69 6c 6c  changes and will
9e30: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 0a   not be counted.
9e40: 2a 2a 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ** by the sqlite
9e50: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b  3_changes() or [
9e60: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
9e70: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
9e80: 6e 73 2e 0a 2a 2a 20 54 6f 20 67 65 74 20 61 6e  ns..** To get an
9e90: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
9ea0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
9eb0: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
9ec0: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
9ed0: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
9ee0: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
9ef0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
9f00: 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65 20  ** {F12241} The 
9f10: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
9f20: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
9f30: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
9f40: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
9f50: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
9f60: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
9f70: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
9f80: 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ATE,.**         
9f90: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
9fa0: 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  ment on the same
9fb0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9fc0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
9fd0: 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20       within the 
9fe0: 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e  same trigger con
9ff0: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
a000: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
a010: 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
a020: 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
a030: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
a040: 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a  ** LIMITATIONS:.
a050: 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49  **.** {U12252} I
a060: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
a070: 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
a080: 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
a090: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a0a0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
a0b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
a0c0: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
a0d0: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
a0e0: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
a0f0: 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64         is unpred
a100: 69 63 74 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65  ictable and unme
a110: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
a120: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
a130: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
a140: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
a150: 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
a160: 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32  s Modified {F122
a170: 36 30 7d 0a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  60}.***.** This 
a180: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
a190: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
a1a0: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
a1b0: 64 0a 2a 2a 20 62 79 20 49 4e 53 45 52 54 2c 20  d.** by INSERT, 
a1c0: 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
a1d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
a1e0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  e the database h
a1f0: 61 6e 64 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65  andle.** was ope
a200: 6e 65 64 2e 20 20 54 68 65 20 63 6f 75 6e 74 20  ned.  The count 
a210: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
a220: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
a230: 69 67 67 65 72 0a 2a 2a 20 63 6f 6e 74 65 78 74  igger.** context
a240: 73 2e 20 20 42 75 74 20 74 68 65 20 63 6f 75 6e  s.  But the coun
a250: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
a260: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
a270: 74 6f 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  to.** implement 
a280: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
a290: 6e 74 73 2c 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  nts, do rollback
a2a0: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
a2b0: 73 73 69 6e 67 2c 0a 2a 2a 20 6f 72 20 44 52 4f  ssing,.** or DRO
a2c0: 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
a2d0: 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
a2e0: 65 73 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  es.** are counte
a2f0: 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
a300: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
a310: 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
a320: 6d 70 6c 65 74 65 64 20 0a 2a 2a 20 28 77 68 65  mpleted .** (whe
a330: 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
a340: 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64  handle is passed
a350: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
a360: 65 74 28 29 5d 20 6f 72 20 0a 2a 2a 20 5b 73 71  et()] or .** [sq
a370: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
a380: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ])..**.** SQLite
a390: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
a3a0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
a3b0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
a3c0: 6f 75 74 0a 2a 2a 20 61 20 57 48 45 52 45 20 63  out.** a WHERE c
a3d0: 6c 61 75 73 65 20 62 79 20 64 72 6f 70 70 69 6e  lause by droppin
a3e0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
a3f0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
a400: 69 73 20 69 73 20 6d 75 63 68 0a 2a 2a 20 66 61  is is much.** fa
a410: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
a420: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
a430: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
a440: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d  al elements form
a450: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
a460: 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73  cause of.** this
a470: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
a480: 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20  he change count 
a490: 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  for "DELETE FROM
a4a0: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a   table" will be.
a4b0: 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65  ** zero regardle
a4c0: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
a4d0: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
a4e0: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
a4f0: 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c  y in the.** tabl
a500: 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  e. To get an acc
a510: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
a520: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
a530: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
a540: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
a550: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
a560: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  stead..**.** See
a570: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
a580: 65 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74  e3_change()] int
a590: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  erface..**.** IN
a5a0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20 0a 2a 2a  VARIANTS:.** .**
a5b0: 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b 73   {F12261} The [s
a5c0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
a5d0: 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20  nges()] returns 
a5e0: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
a5f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
a600: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
a610: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
a620: 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
a630: 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ETE.**          
a640: 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68  statements on th
a650: 65 20 73 61 6d 65 20 5b 73 71 6c 69 74 65 33 20  e same [sqlite3 
a660: 7c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  | database conne
a670: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
a680: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
a690: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
a6a0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
a6b0: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 0a 2a 2a  onnection was.**
a6c0: 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65            create
a6d0: 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  d..**.** LIMITAT
a6e0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
a6f0: 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61  264} If a separa
a700: 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
a710: 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
a720: 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
a730: 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
a740: 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74      while [sqlit
a750: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
a760: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
a770: 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 0a 2a  hen the value .*
a780: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
a790: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
a7a0: 61 62 6c 65 20 61 6e 64 20 75 6e 6d 65 61 6e 69  able and unmeani
a7b0: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
a7c0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
a7d0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
a7e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a7f0: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
a800: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
a810: 46 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12270}.**.** Th
a820: 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
a830: 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
a840: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
a850: 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
a860: 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
a870: 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
a880: 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
a890: 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
a8a0: 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
a8b0: 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
a8c0: 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
a8d0: 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
a8e0: 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
a8f0: 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
a900: 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
a910: 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
a920: 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
a930: 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61  ..**.** It is sa
a940: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
a950: 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
a960: 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
a970: 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
a980: 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
a990: 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
a9a0: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
a9b0: 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
a9c0: 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
a9d0: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
a9e0: 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
a9f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
aa00: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
aa10: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
aa20: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
aa30: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
aa40: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c  .**.** If an SQL
aa50: 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
aa60: 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
aa70: 74 69 6d 65 20 77 68 65 6e 20 73 71 6c 69 74 65  time when sqlite
aa80: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 0a 2a 2a  3_interrupt().**
aa90: 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
aaa0: 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
aab0: 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
aac0: 79 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  y to be interrup
aad0: 74 65 64 2e 0a 2a 2a 20 49 74 20 6d 69 67 68 74  ted..** It might
aae0: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
aaf0: 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 20 41 6e 20 53  pletion..** An S
ab00: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
ab10: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
ab20: 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
ab30: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
ab40: 54 5d 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  T].  If the inte
ab50: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
ab60: 61 74 69 6f 6e 20 69 73 20 61 6e 0a 2a 2a 20 49  ation is an.** I
ab70: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
ab80: 72 20 44 45 4c 45 54 45 20 74 68 61 74 20 69 73  r DELETE that is
ab90: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
aba0: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
abb0: 20 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 65 6e   .** then the en
abc0: 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
abd0: 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
abe0: 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
abf0: 6c 79 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  ly..** A call to
ac00: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
ac10: 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65  pt() has no effe
ac20: 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
ac30: 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
ac40: 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 73   started after s
ac50: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ac60: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
ac70: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
ac80: 0a 2a 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 65  .** {F12271} The
ac90: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
aca0: 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  upt()] interface
acb0: 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20   will force all 
acc0: 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  running.**      
acd0: 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
ace0: 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
acf0: 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  th the same data
ad00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
ad10: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 68  **          to h
ad20: 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65 73  alt after proces
ad30: 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65  sing at most one
ad40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20   additional row 
ad50: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  of.**          d
ad60: 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ata..**.** {F122
ad70: 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74  72} Any SQL stat
ad80: 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e  ement that is in
ad90: 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71  terrupted by [sq
ada0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
adb0: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
adc0: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
add0: 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
ade0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
adf0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d  :.**.** {U12279}
ae00: 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
ae10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
ae20: 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
ae30: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
ae40: 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75  *          is ru
ae50: 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
ae60: 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
ae70: 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
ae80: 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
ae90: 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
aea0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
aeb0: 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
aec0: 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
aed0: 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35 31   Complete {F1051
aee0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
aef0: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
af00: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
af10: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
af20: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
af30: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
af40: 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
af50: 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61   form complete a
af60: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
af70: 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
af80: 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
af90: 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
afa0: 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
afb0: 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
afc0: 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f  rsing.  These ro
afd0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72  utines return tr
afe0: 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  ue if the input 
aff0: 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
b000: 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
b010: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
b020: 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69  .  A statement i
b030: 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
b040: 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
b050: 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
b060: 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
b070: 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65   is not a fragme
b080: 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54  nt of a.** CREAT
b090: 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
b0a0: 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73  ent.  Semicolons
b0b0: 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
b0c0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
b0d0: 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
b0e0: 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
b0f0: 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
b100: 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
b110: 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
b120: 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
b130: 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
b140: 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
b150: 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
b160: 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
b170: 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
b180: 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  t terminator..**
b190: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
b1a0: 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
b1b0: 74 68 65 20 53 51 4c 20 61 6e 64 0a 2a 2a 20 73  the SQL and.** s
b1c0: 6f 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  o will not detec
b1d0: 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
b1e0: 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
b1f0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
b200: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31 7d 20  .**.** {F10511} 
b210: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
b220: 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lete() and sqlit
b230: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
b240: 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  functions.**    
b250: 20 20 20 20 20 20 72 65 74 75 72 6e 20 74 72 75        return tru
b260: 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
b270: 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
b280: 6c 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  last.**         
b290: 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 20   non-whitespace 
b2a0: 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
b2b0: 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
b2c0: 6c 6f 6e 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  lon that.**     
b2d0: 20 20 20 20 20 69 73 20 6e 6f 74 20 69 6e 20 62       is not in b
b2e0: 65 74 77 65 65 6e 20 74 68 65 20 42 45 47 49 4e  etween the BEGIN
b2f0: 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
b300: 45 41 54 45 20 54 52 49 47 47 45 52 0a 2a 2a 20  EATE TRIGGER.** 
b310: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
b320: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  nt..**.** LIMITA
b330: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
b340: 30 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20  0512} The input 
b350: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  to sqlite3_compl
b360: 65 74 65 28 29 20 6d 75 73 74 20 62 65 20 61 20  ete() must be a 
b370: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
b380: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
b390: 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
b3a0: 7b 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70  {U10513} The inp
b3b0: 75 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ut to sqlite3_co
b3c0: 6d 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74 20  mplete16() must 
b3d0: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
b3e0: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
b3f0: 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
b400: 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
b410: 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
b420: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
b430: 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
b440: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
b450: 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
b460: 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
b470: 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
b480: 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
b490: 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
b4a0: 53 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33 31  SY Errors {F1231
b4b0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0}.**.** This ro
b4c0: 75 74 69 6e 65 20 69 64 65 6e 74 69 66 69 65 73  utine identifies
b4d0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
b4e0: 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
b4f0: 62 65 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  be.** invoked wh
b500: 65 6e 65 76 65 72 20 61 6e 20 61 74 74 65 6d 70  enever an attemp
b510: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
b520: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
b530: 6c 65 20 0a 2a 2a 20 74 68 61 74 20 61 6e 6f 74  le .** that anot
b540: 68 65 72 20 74 68 72 65 61 64 20 6f 72 20 70 72  her thread or pr
b550: 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
b560: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  ..** If the busy
b570: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
b580: 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
b590: 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
b5a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
b5b0: 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
b5c0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
b5d0: 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
b5e0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 49 66 20  the lock..** If 
b5f0: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
b600: 6b 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  k is not NULL, t
b610: 68 65 6e 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 62  hen the.** callb
b620: 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
b630: 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
b640: 75 6d 65 6e 74 73 2e 20 20 54 68 65 0a 2a 2a 20  uments.  The.** 
b650: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
b660: 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
b670: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
b680: 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
b690: 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
b6a0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
b6b0: 68 69 73 20 72 6f 75 74 69 6e 65 2e 20 20 54 68  his routine.  Th
b6c0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b6d0: 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
b6e0: 6c 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ler is the numbe
b6f0: 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
b700: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
b710: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
b720: 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
b730: 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 20 49  cking event.   I
b740: 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
b750: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
b760: 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
b770: 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
b780: 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
b790: 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
b7a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
b7b0: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
b7c0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
b7d0: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
b7e0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
b7f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
b800: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
b810: 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
b820: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
b830: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
b840: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
b850: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
b860: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
b870: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
b880: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
b890: 68 61 74 0a 2a 2a 20 69 74 20 77 69 6c 6c 20 62  hat.** it will b
b8a0: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  e invoked when t
b8b0: 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
b8c0: 74 65 6e 74 69 6f 6e 2e 0a 2a 2a 20 49 66 20 53  tention..** If S
b8d0: 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
b8e0: 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
b8f0: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
b900: 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 0a  could result in.
b910: 2a 2a 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  ** a deadlock, i
b920: 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
b930: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
b940: 54 45 5f 42 55 53 59 5d 20 6f 72 0a 2a 2a 20 5b  TE_BUSY] or.** [
b950: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
b960: 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
b970: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 0a 2a 2a   invoking the.**
b980: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
b990: 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
b9a0: 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
b9b0: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
b9c0: 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
b9d0: 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
b9e0: 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
b9f0: 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
ba00: 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
ba10: 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
ba20: 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
ba30: 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
ba40: 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
ba50: 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
ba60: 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
ba70: 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
ba80: 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
ba90: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
baa0: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
bab0: 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
bac0: 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
bad0: 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
bae0: 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
baf0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
bb00: 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
bb10: 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
bb20: 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
bb30: 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
bb40: 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
bb50: 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
bb60: 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
bb70: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
bb80: 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
bb90: 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
bba0: 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
bbb0: 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
bbc0: 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
bbd0: 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
bbe0: 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
bbf0: 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
bc00: 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
bc10: 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
bc20: 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
bc30: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  LL..**.** The [S
bc40: 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
bc50: 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
bc60: 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
bc70: 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
bc80: 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
bc90: 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
bca0: 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
bcb0: 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
bcc0: 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
bcd0: 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
bce0: 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
bcf0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
bd00: 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
bd10: 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
bd20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
bd30: 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
bd40: 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
bd50: 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
bd60: 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
bd70: 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
bd80: 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
bd90: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
bda0: 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
bdb0: 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
bdc0: 61 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73  aders.  If it is
bdd0: 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
bde0: 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
bdf0: 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
be00: 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
be10: 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
be20: 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
be30: 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
be40: 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
be50: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
be60: 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
be70: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
be80: 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
be90: 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
bea0: 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73  _BLOCKED].  This
beb0: 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
bec0: 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
bed0: 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
bee0: 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
bef0: 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
bf00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
bf10: 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67  //www.sqlite.org
bf20: 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
bf30: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
bf40: 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
bf50: 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
bf60: 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
bf70: 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
bf80: 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
bf90: 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
bfa0: 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 09 0a 2a  important..**..*
bfb0: 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  * There can only
bfc0: 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
bfd0: 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
bfe0: 64 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62  d for each datab
bff0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
c000: 6e 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  n.  Setting a ne
c010: 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
c020: 6c 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f  lears any previo
c030: 75 73 20 6f 6e 65 2e 20 0a 2a 2a 20 4e 6f 74 65  us one. .** Note
c040: 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
c050: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
c060: 6f 75 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f  out()] will also
c070: 20 73 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a   set or clear.**
c080: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c090: 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  r..**.** INVARIA
c0a0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  NTS:.**.** {F123
c0b0: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
c0c0: 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
c0d0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
c0e0: 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
c0f0: 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ler.**          
c100: 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20  callback in the 
c110: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c120: 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  ion identified b
c130: 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 20 20  y the 1st.**    
c140: 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
c150: 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 79 20  with a new busy 
c160: 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 66 69  handler identifi
c170: 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 61 6e  ed by the 2nd an
c180: 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  d 3rd.**        
c190: 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a    parameters..**
c1a0: 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 68 65  .** {F12312} The
c1b0: 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 68 61   default busy ha
c1c0: 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 64 61  ndler for new da
c1d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c1e0: 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ns is NULL..**.*
c1f0: 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 6e 20  * {F12314} When 
c200: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74 61  two or more data
c210: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c220: 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
c230: 61 63 68 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ache,.**        
c240: 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c    the busy handl
c250: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
c260: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
c270: 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a  urrently using.*
c280: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
c290: 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ache is invoked 
c2a0: 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65  when the cache e
c2b0: 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b  ncounters a lock
c2c0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36 7d  ..**.** {F12316}
c2d0: 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   If a busy handl
c2e0: 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
c2f0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  rns zero, then t
c300: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20  he SQLite.**    
c310: 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
c320: 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
c330: 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20  e locking event 
c340: 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  will return.**  
c350: 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
c360: 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  BUSY]..**.** {F1
c370: 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 69 6c  2318} SQLite wil
c380: 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75  l invokes the bu
c390: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20  sy handler with 
c3a0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 20 77 68 69  two argument whi
c3b0: 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ch.**          a
c3c0: 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  re a copy of the
c3d0: 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65   pointer supplie
c3e0: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
c3f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
c400: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
c410: 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61  usy_handler()] a
c420: 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68  nd a count of th
c430: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f  e number of prio
c440: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
c450: 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
c460: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
c470: 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
c480: 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  ng event..**.** 
c490: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
c4a0: 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20 62 75  ** {U12319} A bu
c4b0: 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f 75 6c  sy handler shoul
c4c0: 64 20 6e 6f 74 20 63 61 6c 6c 20 63 6c 6f 73 65  d not call close
c4d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
c4e0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
c4f0: 20 20 20 20 20 6f 72 20 70 72 65 70 61 72 65 64       or prepared
c500: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
c510: 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
c520: 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
c530: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
c540: 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
c550: 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
c560: 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
c570: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
c580: 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b  A Busy Timeout {
c590: 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12340}.**.** Th
c5a0: 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
c5b0: 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
c5c0: 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
c5d0: 61 6e 64 6c 65 72 5d 0a 2a 2a 20 74 68 61 74 20  andler].** that 
c5e0: 73 6c 65 65 70 73 20 66 6f 72 20 61 20 77 68 69  sleeps for a whi
c5f0: 6c 65 20 77 68 65 6e 20 61 0a 2a 2a 20 74 61 62  le when a.** tab
c600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54  le is locked.  T
c610: 68 65 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  he handler will 
c620: 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
c630: 69 6d 65 73 20 75 6e 74 69 6c 20 0a 2a 2a 20 61  imes until .** a
c640: 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
c650: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
c660: 65 70 69 6e 67 20 68 61 76 65 20 62 65 65 6e 20  eping have been 
c670: 64 6f 6e 65 2e 20 7b 46 31 32 33 34 33 7d 20 41  done. {F12343} A
c680: 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69 6c  fter.** "ms" mil
c690: 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
c6a0: 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64 6c  eping, the handl
c6b0: 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
c6c0: 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73 71  ch.** causes [sq
c6d0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
c6e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c6f0: 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
c700: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
c710: 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
c720: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
c730: 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
c740: 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
c750: 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
c760: 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
c770: 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
c780: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
c790: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
c7a0: 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
c7b0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
c7c0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
c7d0: 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
c7e0: 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66 69  handler was defi
c7f0: 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67 20  ned  .** (using 
c800: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
c810: 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
c820: 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
c830: 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
c840: 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
c850: 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
c860: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
c870: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d  :.**.** {F12341}
c880: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
c890: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75  sy_timeout()] fu
c8a0: 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65 73  nction overrides
c8b0: 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20   any prior.**   
c8c0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
c8d0: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
c8e0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  or [sqlite3_busy
c8f0: 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74  _handler()] sett
c900: 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
c910: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
c920: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
c930: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20  .**.** {F12343} 
c940: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
c950: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
c960: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
c970: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a   is less than.**
c980: 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71 75            or equ
c990: 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e  al to zero, then
c9a0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
c9b0: 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f 20  r is cleared so 
c9c0: 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
c9d0: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
c9e0: 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69  locking events i
c9f0: 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
ca00: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
ca10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20  .**.** {F12344} 
ca20: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
ca30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
ca40: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
ca50: 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a   is a positive.*
ca60: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
ca70: 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79  r N, then a busy
ca80: 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74 20   handler is set 
ca90: 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
caa0: 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
cab0: 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
cac0: 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46 53  ethod in the VFS
cad0: 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69 6c   interface until
cae0: 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 20   either the.**  
caf0: 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65          lock cle
cb00: 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
cb10: 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
cb20: 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64 20  p time reported 
cb30: 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
cb40: 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
cb50: 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
cb60: 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
cb70: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
cb80: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
cb90: 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
cba0: 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
cbb0: 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
cbc0: 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 46  nning Queries {F
cbd0: 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66  12370}.**.** Def
cbe0: 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
cbf0: 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
cc00: 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
cc10: 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
cc20: 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
cc30: 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
cc40: 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
cc50: 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
cc60: 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
cc70: 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
cc80: 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
cc90: 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
cca0: 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
ccb0: 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
ccc0: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
ccd0: 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
cce0: 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
ccf0: 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
cd00: 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
cd10: 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
cd20: 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
cd30: 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
cd40: 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
cd50: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
cd60: 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
cd70: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
cd80: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
cd90: 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
cda0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
cdb0: 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
cdc0: 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
cdd0: 69 6e 67 73 2e 20 20 54 68 65 72 65 20 61 72 65  ings.  There are
cde0: 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
cdf0: 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
ce00: 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 4d   .** The first M
ce10: 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 20   pointers point 
ce20: 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
ce30: 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
ce40: 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  .** contain the 
ce50: 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
ce60: 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
ce70: 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
ce80: 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
ce90: 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
cea0: 0a 2a 2a 20 76 61 6c 75 65 73 20 61 72 65 20 67  .** values are g
ceb0: 69 76 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ive a NULL point
cec0: 65 72 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  er.  All other v
ced0: 61 6c 75 65 73 20 61 72 65 20 69 6e 0a 2a 2a 20  alues are in.** 
cee0: 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
cef0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
cf00: 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
cf10: 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
cf20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
cf30: 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
cf40: 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
cf50: 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 73  e might consists
cf60: 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
cf70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cf80: 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
cf90: 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
cfa0: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
cfb0: 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
cfc0: 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
cfd0: 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
cfe0: 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
cff0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
d000: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
d010: 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
d020: 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
d030: 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
d040: 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
d050: 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
d060: 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
d070: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
d080: 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
d090: 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
d0a0: 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
d0b0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
d0c0: 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
d0d0: 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
d0e0: 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
d0f0: 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
d100: 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
d110: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
d120: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
d130: 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
d140: 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
d150: 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
d160: 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
d170: 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
d180: 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
d190: 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
d1a0: 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
d1b0: 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
d1c0: 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
d1d0: 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
d1e0: 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
d1f0: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
d200: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
d210: 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
d220: 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
d230: 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
d240: 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
d250: 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
d260: 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
d270: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
d280: 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
d290: 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
d2a0: 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
d2b0: 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
d2c0: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
d2d0: 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
d2e0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
d2f0: 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
d300: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
d310: 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
d320: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
d330: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
d340: 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
d350: 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
d360: 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
d370: 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
d380: 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
d390: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
d3a0: 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
d3b0: 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
d3c0: 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
d3d0: 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
d3e0: 75 72 6e 73 20 61 20 5b 72 65 73 75 6c 74 20 74  urns a [result t
d3f0: 61 62 6c 65 5d 20 74 6f 20 74 68 65 0a 2a 2a 20  able] to the.** 
d400: 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
d410: 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
d420: 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
d430: 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
d440: 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
d450: 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75  d using the resu
d460: 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 20 0a 2a  lt, it should .*
d470: 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
d480: 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
d490: 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
d4a0: 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
d4b0: 6e 20 6f 72 64 65 72 20 74 6f 20 0a 2a 2a 20 72  n order to .** r
d4c0: 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
d4d0: 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
d4e0: 63 2d 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  c-ed.  Because o
d4f0: 66 20 74 68 65 20 77 61 79 20 74 68 65 20 0a 2a  f the way the .*
d500: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
d510: 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
d520: 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
d530: 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
d540: 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
d550: 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
d560: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
d570: 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
d580: 20 20 4f 6e 6c 79 20 0a 2a 2a 20 5b 73 71 6c 69    Only .** [sqli
d590: 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
d5a0: 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
d5b0: 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
d5c0: 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
d5d0: 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
d5e0: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
d5f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
d600: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
d610: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
d620: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
d630: 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
d640: 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
d650: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
d660: 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
d670: 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
d680: 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
d690: 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
d6a0: 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
d6b0: 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
d6c0: 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
d6d0: 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
d6e0: 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
d6f0: 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
d700: 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
d710: 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
d720: 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
d730: 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
d740: 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
d750: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
d760: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
d770: 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
d780: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
d790: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
d7a0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  TS:.**.** {F1237
d7b0: 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33  1} If a [sqlite3
d7c0: 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61  _get_table()] fa
d7d0: 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  ils a memory all
d7e0: 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a  ocation, then.**
d7f0: 20 20 20 20 20 20 20 20 20 20 69 74 20 66 72 65            it fre
d800: 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  es the result ta
d810: 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72  ble under constr
d820: 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74  uction, aborts t
d830: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71  he.**          q
d840: 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c  uery in process,
d850: 20 73 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65   skips any subse
d860: 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73  quent queries, s
d870: 65 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ets the.**      
d880: 20 20 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74      *resultp out
d890: 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  put pointer to N
d8a0: 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ULL and returns 
d8b0: 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
d8c0: 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49  **.** {F12373} I
d8d0: 66 20 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61  f the ncolumn pa
d8e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
d8f0: 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
d900: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
d910: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
d920: 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
d930: 28 29 5d 20 77 72 69 74 65 20 74 68 65 20 6e 75  ()] write the nu
d940: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
d950: 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
d960: 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
d970: 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
d980: 2a 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20  *ncolumn if the 
d990: 71 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20  query is.**     
d9a0: 20 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20       successful 
d9b0: 28 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  (if the function
d9c0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
d9d0: 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  OK)..**.** {F123
d9e0: 37 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20  74} If the nrow 
d9f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
da00: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
da10: 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
da20: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
da30: 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
da40: 6c 65 28 29 5d 20 77 72 69 74 65 20 74 68 65 20  le()] write the 
da50: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
da60: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
da70: 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
da80: 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
da90: 6e 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72  nrow if the quer
daa0: 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  y is.**         
dab0: 20 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20   successful (if 
dac0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
dad0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e  urns SQLITE_OK).
dae0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20  .**.** {F12373} 
daf0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
db00: 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69  _table()] functi
db10: 6f 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f  on sets its *nco
db20: 6c 75 6d 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20  lumn value.**   
db30: 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 75         to the nu
db40: 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
db50: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
db60: 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
db70: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
db80: 20 20 73 71 6c 20 70 61 72 61 6d 65 74 65 72 2c    sql parameter,
db90: 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74   or to zero if t
dba0: 68 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20  he query in sql 
dbb0: 68 61 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20  has an empty.** 
dbc0: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
dbd0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54  set..**.** LIMIT
dbe0: 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  ATIONS:.**.** {F
dbf0: 31 32 33 38 30 7d 20 45 72 72 6f 72 20 63 6f 64  12380} Error cod
dc00: 65 73 20 72 65 74 75 72 6e 65 64 20 5b 73 71 6c  es returned [sql
dc10: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
dc20: 5d 20 6d 69 67 68 74 20 6e 6f 74 20 62 65 0a 2a  ] might not be.*
dc30: 2a 20 20 20 20 20 20 20 20 20 20 73 65 65 6e 20  *          seen 
dc40: 62 79 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  by subsequent ca
dc50: 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
dc60: 65 72 72 63 6f 64 65 28 29 5d 2c 20 6f 72 0a 2a  errcode()], or.*
dc70: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
dc80: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
dc90: 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  *.*/.int sqlite3
dca0: 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
dcb0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
dcc0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
dcd0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
dce0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
dcf0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
dd00: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
dd10: 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c 74 2c 20  har ***pResult, 
dd20: 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20       /* Results 
dd30: 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
dd40: 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20    int *nrow,    
dd50: 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
dd60: 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
dd70: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
dd80: 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c  .  int *ncolumn,
dd90: 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
dda0: 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
ddb0: 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
ddc0: 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  e */.  char **er
ddd0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 2f 2a 20  rmsg         /* 
dde0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
ddf0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
de00: 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
de10: 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
de20: 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
de30: 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
de40: 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
de50: 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37 34 30  Functions {F1740
de60: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0}.**.** These r
de70: 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
de80: 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
de90: 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
dea0: 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
deb0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
dec0: 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
ded0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
dee0: 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
def0: 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
df00: 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
df10: 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
df20: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
df30: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
df40: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
df50: 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
df60: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
df70: 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
df80: 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
df90: 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
dfa0: 65 65 28 29 5d 2e 20 20 20 42 6f 74 68 20 72 6f  ee()].   Both ro
dfb0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
dfc0: 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
dfd0: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
dfe0: 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
dff0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
e000: 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
e010: 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
e020: 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
e030: 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
e040: 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
e050: 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
e060: 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
e070: 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
e080: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
e090: 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
e0a0: 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
e0b0: 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
e0c0: 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
e0d0: 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
e0e0: 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
e0f0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
e100: 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
e110: 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
e120: 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
e130: 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
e140: 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
e150: 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
e160: 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
e170: 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
e180: 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
e190: 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
e1a0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
e1b0: 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
e1c0: 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
e1d0: 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
e1e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
e1f0: 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
e200: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
e210: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
e220: 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
e230: 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
e240: 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
e250: 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
e260: 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
e270: 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
e280: 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
e290: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
e2a0: 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
e2b0: 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
e2c0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
e2d0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
e2e0: 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
e2f0: 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
e300: 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
e310: 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
e320: 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
e330: 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
e340: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
e350: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
e360: 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
e370: 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
e380: 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
e390: 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
e3a0: 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
e3b0: 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
e3c0: 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
e3d0: 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
e3e0: 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
e3f0: 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
e400: 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
e410: 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
e420: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
e430: 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
e440: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
e450: 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
e460: 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
e470: 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
e480: 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
e490: 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
e4a0: 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
e4b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
e4c0: 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
e4d0: 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d 61 74 74  l printf formatt
e4e0: 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
e4f0: 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
e500: 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
e510: 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
e520: 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
e530: 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69  *.** The %q opti
e540: 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
e550: 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
e560: 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
e570: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
e580: 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
e590: 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
e5a0: 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
e5b0: 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
e5c0: 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
e5d0: 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
e5e0: 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
e5f0: 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f   literal.  By do
e600: 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
e610: 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
e620: 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
e630: 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
e640: 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
e650: 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
e660: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
e670: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73 6f 20 73  or example, so s
e680: 6f 6d 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  ome string varia
e690: 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ble contains tex
e6a0: 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
e6b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
e6c0: 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
e6d0: 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
e6e0: 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
e6f0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
e700: 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
e710: 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
e720: 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
e730: 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
e740: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
e750: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
e760: 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
e770: 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
e780: 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
e790: 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
e7a0: 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
e7b0: 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
e7c0: 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
e7d0: 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
e7e0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
e7f0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
e800: 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
e810: 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
e820: 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
e830: 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
e840: 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
e850: 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
e860: 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
e870: 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
e880: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
e890: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
e8a0: 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
e8b0: 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
e8c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
e8d0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
e8e0: 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
e8f0: 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
e900: 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
e910: 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
e920: 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
e930: 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
e940: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
e950: 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
e960: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
e970: 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
e980: 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
e990: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
e9a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
e9b0: 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
e9c0: 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
e9d0: 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
e9e0: 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73 68 6f 75  rule you.** shou
e9f0: 6c 64 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ld always use %q
ea00: 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
ea10: 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
ea20: 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
ea30: 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a   .** literal..**
ea40: 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
ea50: 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
ea60: 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
ea70: 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
ea80: 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
ea90: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
eaa0: 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 4f 72  otal string.  Or
eab0: 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
eac0: 72 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e  r in the argumen
ead0: 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20 61 20 4e  t.** list is a N
eae0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
eaf0: 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
eb00: 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
eb10: 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a 2a 20 71  hout single.** q
eb20: 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20  uotes) in place 
eb30: 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e  of the %Q option
eb40: 2e 20 7b 45 4e 44 7d 20 20 53 6f 2c 20 66 6f 72  . {END}  So, for
eb50: 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
eb60: 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
eb70: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
eb80: 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
eb90: 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
eba0: 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
ebb0: 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
ebc0: 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
ebd0: 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
ebe0: 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
ebf0: 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
ec00: 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
ec10: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
ec20: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
ec30: 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
ec40: 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
ec50: 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
ec60: 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
ec70: 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
ec80: 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
ec90: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
eca0: 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d  ** The "%z" form
ecb0: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
ecc0: 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65  rks exactly like
ecd0: 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a   "%s" with the.*
ece0: 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
ecf0: 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
ed00: 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
ed10: 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
ed20: 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
ed30: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
ed40: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
ed50: 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45  input string. {E
ed60: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ND}.**.** INVARI
ed70: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
ed80: 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  403}  The [sqlit
ed90: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e  e3_mprintf()] an
eda0: 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  d [sqlite3_vmpri
edb0: 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
edc0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  s.**           r
edd0: 65 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69  eturn either poi
ede0: 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
edf0: 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
ee00: 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a  trings held in.*
ee10: 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  *           memo
ee20: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ee30: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ee40: 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e  ()] or NULL poin
ee50: 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20  ters if.**      
ee60: 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b       a call to [
ee70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
ee80: 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ] fails..**.** {
ee90: 46 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71  F17406}  The [sq
eea0: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
eeb0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74  ] interface writ
eec0: 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  es a zero-termin
eed0: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
eee0: 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
eef0: 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70  nto the buffer p
ef00: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
ef10: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
ef20: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70  r.**           p
ef30: 72 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65  rovided that the
ef40: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
ef50: 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
ef60: 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
ef70: 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69  7407}  The [sqli
ef80: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
ef90: 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
efa0: 6f 74 20 77 72 69 74 65 73 20 73 6c 6f 74 73 20  ot writes slots 
efb0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
efc0: 69 74 73 20 6f 75 74 70 75 74 20 62 75 66 66 65  its output buffe
efd0: 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61  r (the second pa
efe0: 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65  rameter) outside
eff0: 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20   the range.**   
f000: 20 20 20 20 20 20 20 20 6f 66 20 30 20 74 68 72          of 0 thr
f010: 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20  ough N-1 (where 
f020: 4e 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  N is the first p
f030: 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20  arameter).**    
f040: 20 20 20 20 20 20 20 72 65 67 61 72 64 6c 65 73         regardles
f050: 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20  s of the length 
f060: 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a  of the string.**
f070: 20 20 20 20 20 20 20 20 20 20 20 72 65 71 75 65             reque
f080: 73 74 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d  sted by the form
f090: 61 74 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  at specification
f0a0: 2e 0a 2a 2a 20 20 20 0a 2a 2f 0a 63 68 61 72 20  ..**   .*/.char 
f0b0: 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
f0c0: 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
f0d0: 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
f0e0: 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
f0f0: 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
f100: 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
f110: 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
f120: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
f130: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
f140: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
f150: 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
f160: 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a 2a 2a  m {F17300}.**.**
f170: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f180: 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
f190: 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
f1a0: 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
f1b0: 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
f1c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
f1d0: 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
f1e0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
f1f0: 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
f200: 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
f210: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
f220: 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
f230: 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 77 69  tion.  The.** wi
f240: 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
f250: 61 74 69 76 65 20 6d 61 6c 6c 6f 63 20 61 6e 64  ative malloc and
f260: 20 66 72 65 65 20 66 6f 72 20 73 6f 6d 65 20 6f   free for some o
f270: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
f280: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c   The sqlite3_mal
f290: 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
f2a0: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
f2b0: 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
f2c0: 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
f2d0: 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
f2e0: 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
f2f0: 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
f300: 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
f310: 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
f320: 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
f330: 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
f340: 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
f350: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
f360: 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
f370: 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
f380: 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
f390: 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
f3a0: 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
f3b0: 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
f3c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
f3d0: 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c  *.** Calling sql
f3e0: 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
f3f0: 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
f400: 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
f410: 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
f420: 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
f430: 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
f440: 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
f450: 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
f460: 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
f470: 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
f480: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
f490: 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
f4a0: 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
f4b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
f4c0: 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
f4d0: 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
f4e0: 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
f4f0: 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
f500: 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
f510: 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
f520: 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
f530: 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
f540: 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
f550: 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
f560: 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
f570: 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
f580: 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
f590: 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
f5a0: 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
f5b0: 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
f5c0: 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
f5d0: 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
f5e0: 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
f5f0: 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
f600: 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
f610: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
f620: 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
f630: 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
f640: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f650: 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65   or sqlite3_free
f660: 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  ()..**.** {F1731
f670: 30 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  0} The sqlite3_r
f680: 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
f690: 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
f6a0: 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
f6b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f6c0: 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
f6d0: 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
f6e0: 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
f6f0: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
f700: 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
f710: 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
f720: 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
f730: 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
f740: 7b 46 31 37 33 31 31 7d 20 49 66 20 74 68 65 20  {F17311} If the 
f750: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
f760: 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
f770: 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
f780: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
f790: 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
f7a0: 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
f7b0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
f7c0: 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
f7d0: 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
f7e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
f7f0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
f800: 2a 20 7b 46 31 37 33 31 32 7d 20 49 66 20 74 68  * {F17312} If th
f810: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
f820: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
f830: 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
f840: 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
f850: 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
f860: 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
f870: 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
f880: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
f890: 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
f8a0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
f8b0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
f8c0: 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 7b 46 31 37 33  lloc()..** {F173
f8d0: 31 33 7d 20 53 71 6c 69 74 65 33 5f 72 65 61 6c  13} Sqlite3_real
f8e0: 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
f8f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
f900: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f910: 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
f920: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
f930: 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
f940: 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
f950: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 7b 46  available..** {F
f960: 31 37 33 31 34 7d 20 49 66 20 4d 20 69 73 20 74  17314} If M is t
f970: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
f980: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
f990: 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
f9a0: 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
f9b0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
f9c0: 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
f9d0: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
f9e0: 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
f9f0: 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
fa00: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
fa10: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fa20: 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 7b  n is freed..** {
fa30: 46 31 37 33 31 35 7d 20 49 66 20 73 71 6c 69 74  F17315} If sqlit
fa40: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
fa50: 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
fa60: 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
fa70: 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
fa80: 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  reed..**.** {F17
fa90: 33 31 36 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20  316} The memory 
faa0: 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
fab0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
fac0: 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
fad0: 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
fae0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
faf0: 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
fb00: 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a  undary. {END}.**
fb10: 0a 2a 2a 20 7b 46 31 37 33 38 31 7d 20 54 68 65  .** {F17381} The
fb20: 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
fb30: 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68  ntation.** of th
fb40: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
fb50: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
fb60: 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  es the malloc(),
fb70: 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61 6e   realloc().** an
fb80: 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
fb90: 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
fba0: 64 20 43 20 6c 69 62 72 61 72 79 2e 20 7b 46 31  d C library. {F1
fbb0: 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
fbc0: 66 20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  f .** SQLite is 
fbd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
fbe0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 43 20 70 72  e following C pr
fbf0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
fc00: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
fc10: 74 65 3e 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52  te> SQLITE_MEMOR
fc20: 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69  Y_SIZE=<i>NNN</i
fc30: 3e 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  > </blockquote>.
fc40: 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 3c 69 3e 4e  **.** where <i>N
fc50: 4e 4e 3c 2f 69 3e 20 69 73 20 61 6e 20 69 6e 74  NN</i> is an int
fc60: 65 67 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  eger, then SQLit
fc70: 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
fc80: 63 0a 2a 2a 20 61 72 72 61 79 20 6f 66 20 61 74  c.** array of at
fc90: 20 6c 65 61 73 74 20 3c 69 3e 4e 4e 4e 3c 2f 69   least <i>NNN</i
fca0: 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
fcb0: 61 6e 64 20 75 73 65 20 74 68 61 74 20 61 72 72  and use that arr
fcc0: 61 79 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  ay.** for all of
fcd0: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
fce0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
fcf0: 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
fd00: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 6d 65 6d 6f 72  itional.** memor
fd10: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
fd20: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
fd30: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
fd40: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
fd50: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
fd60: 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
fd70: 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
fd80: 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
fd90: 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
fda0: 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
fdb0: 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
fdc0: 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
fdd0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
fde0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
fdf0: 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
fe00: 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
fe10: 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
fe20: 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
fe30: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
fe40: 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
fe50: 65 0a 2a 2a 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  e.** used..**.**
fe60: 20 54 68 65 20 77 69 6e 64 6f 77 73 20 4f 53 20   The windows OS 
fe70: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
fe80: 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
fe90: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
fea0: 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
feb0: 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
fec0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
fed0: 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
fee0: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
fef0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
ff00: 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
ff10: 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
ff20: 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
ff30: 6c 61 72 20 77 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar windows.** i
ff40: 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
ff50: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ff60: 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
ff70: 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
ff80: 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
ff90: 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
ffa0: 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
ffb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
ffc0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ffd0: 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
ffe0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
fff0: 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b   {F17303}  The [
10000 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10010 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
10020 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
10030 6e 74 65 72 20 74 6f 20 0a 2a 2a 20 20 20 20 20  nter to .**     
10040 20 20 20 20 20 20 6e 65 77 6c 79 20 63 68 65 63        newly chec
10050 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
10060 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
10070 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
10080 20 20 20 20 20 20 20 20 20 28 77 68 65 72 65 20           (where 
10090 4e 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  N is the first p
100a0 61 72 61 6d 65 74 65 72 29 20 74 68 61 74 20 69  arameter) that i
100b0 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
100c0 2c 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  , .**           
100d0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
100e0 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
100f0 6c 65 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68  le to fulfill th
10100 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a  e request..**.**
10110 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b   {F17304}  The [
10120 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
10130 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
10140 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
10150 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  er if.**        
10160 20 20 20 69 74 73 20 70 61 72 61 6d 65 74 65 72     its parameter
10170 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
10180 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a   equal to zero..
10190 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 35 7d 20 20  **.** {F17305}  
101a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  The [sqlite3_fre
101b0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  e()] interface r
101c0 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70  eleases memory p
101d0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
101e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
101f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
10200 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
10210 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
10220 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b  **           mak
10230 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65  ing it available
10240 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a   for reuse..**.*
10250 2a 20 7b 46 31 37 33 30 36 7d 20 20 49 66 20 74  * {F17306}  If t
10260 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  he argument to [
10270 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
10280 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
10290 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
102a0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
102b0 33 5f 66 72 65 65 28 29 5d 20 63 61 6c 6c 20 69  3_free()] call i
102c0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
102d0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31  op..**.** {F1731
102e0 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  0}  A call to [s
102f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 5d 28  qlite3_realloc](
10300 30 2c 4e 29 20 69 73 20 65 71 75 69 76 61 6c 65  0,N) is equivale
10310 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
10320 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
10330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 28 4e 29  lite3_malloc](N)
10340 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 32 7d  ..**.** {F17312}
10350 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
10360 69 74 65 33 5f 72 65 61 6c 6c 6f 63 5d 28 70 2c  ite3_realloc](p,
10370 30 29 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  0) is equivalent
10380 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
10390 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
103a0 74 65 33 5f 66 72 65 65 5d 28 70 29 2e 0a 2a 2a  te3_free](p)..**
103b0 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20 54 68  .** {F17315}  Th
103c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
103d0 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  es [sqlite3_mall
103e0 6f 63 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  oc], [sqlite3_re
103f0 61 6c 6c 6f 63 5d 2c 0a 2a 2a 20 20 20 20 20 20  alloc],.**      
10400 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65       and [sqlite
10410 33 5f 66 72 65 65 5d 20 66 6f 72 20 61 6c 6c 20  3_free] for all 
10420 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c  of its memory al
10430 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  location and.** 
10440 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f            deallo
10450 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  cation..**.** {F
10460 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
10470 69 74 65 33 5f 72 65 61 6c 6c 6f 63 5d 20 69 6e  ite3_realloc] in
10480 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
10490 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72  either a pointer
104a0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 20   to a block.**  
104b0 20 20 20 20 20 20 20 20 20 6f 66 20 63 68 65 63           of chec
104c0 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f  ked-out memory o
104d0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
104e0 65 73 20 69 6e 20 73 69 7a 65 20 28 77 68 65 72  es in size (wher
104f0 65 20 4e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e N.**          
10500 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
10510 61 72 61 6d 65 74 65 72 29 20 74 68 61 74 20 69  arameter) that i
10520 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
10530 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20  , or a NULL.**  
10540 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
10550 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 31 7d  ..**.** {F17321}
10560 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
10570 72 65 61 6c 6c 6f 63 5d 20 72 65 74 75 72 6e 73  realloc] returns
10580 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
10590 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
105a0 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
105b0 73 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e  s K bytes of con
105c0 74 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 62 75  tent from the bu
105d0 66 66 65 72 20 67 69 76 65 6e 20 62 79 20 74 68  ffer given by th
105e0 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  e first.**      
105f0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 69       parameter i
10600 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 20 61 6c  nto the newly al
10610 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 2c 20  located buffer, 
10620 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 73  where K is the s
10630 6d 61 6c 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20  maller.**       
10640 20 20 20 20 6f 66 20 4e 20 61 6e 64 20 74 68 65      of N and the
10650 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
10660 66 65 72 20 67 69 76 65 6e 20 69 6e 20 74 68 65  fer given in the
10670 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
10680 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d  ..**.** {F17322}
10690 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
106a0 72 65 61 6c 6c 6f 63 5d 20 72 65 74 75 72 6e 73  realloc] returns
106b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
106c0 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
106d0 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65 61             relea
106e0 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20 67  ses the buffer g
106f0 69 76 65 6e 20 69 6e 20 74 68 65 20 66 69 72 73  iven in the firs
10700 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
10710 2a 2a 20 7b 46 31 37 33 32 33 7d 20 20 57 68 65  ** {F17323}  Whe
10720 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
10730 6f 63 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  oc] returns NULL
10740 2c 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69  , the buffer poi
10750 6e 74 65 64 20 74 6f 20 62 79 0a 2a 2a 20 20 20  nted to by.**   
10760 20 20 20 20 20 20 20 20 74 68 65 20 66 69 72 73          the firs
10770 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  t parameter is n
10780 6f 74 20 72 65 6c 65 61 73 65 64 20 61 6e 64 20  ot released and 
10790 69 74 73 20 63 6f 6e 74 65 6e 74 20 69 73 20 6e  its content is n
107a0 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ot.**           
107b0 61 6c 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c  altered..**.** L
107c0 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
107d0 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20  * {U17350}  The 
107e0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
107f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
10800 65 65 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ee] and [sqlite3
10810 5f 72 65 61 6c 6c 6f 63 5d 0a 2a 2a 20 20 20 20  _realloc].**    
10820 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65         must be e
10830 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
10840 73 65 20 61 20 70 6f 69 6e 74 65 72 20 6f 62 74  se a pointer obt
10850 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
10860 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
10870 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
10880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 6f  qlite3_malloc] o
10890 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
108a0 6f 63 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  oc] that has.** 
108b0 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65            not be
108c0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
108d0 2a 2a 20 7b 55 31 37 33 35 31 7d 20 20 54 68 65  ** {U17351}  The
108e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
108f0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
10900 69 74 65 20 6d 65 6d 6f 72 79 20 61 6e 79 20 70  ite memory any p
10910 61 72 74 20 6f 66 20 0a 2a 2a 20 20 20 20 20 20  art of .**      
10920 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
10930 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
10940 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
10950 64 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 2a 73  d..**.*/.void *s
10960 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
10970 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
10980 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
10990 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
109a0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
109b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
109c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
109d0 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 46  or Statistics {F
109e0 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  17370}.**.** In 
109f0 61 64 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20  addition to the 
10a00 62 61 73 69 63 20 74 68 72 65 65 20 61 6c 6c 6f  basic three allo
10a10 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
10a20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
10a30 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
10a40 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
10a50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10a60 5d 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  ],.** the memory
10a70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
10a80 79 73 74 65 6d 20 69 6e 63 6c 75 64 65 64 20 77  ystem included w
10a90 69 74 68 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ith the SQLite.*
10aa0 2a 20 73 6f 75 72 63 65 73 20 70 72 6f 76 69 64  * sources provid
10ab0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
10ac0 73 20 73 68 6f 77 6e 20 68 65 72 65 2e 0a 2a 2a  s shown here..**
10ad0 0a 2a 2a 20 7b 46 31 37 33 37 31 7d 20 54 68 65  .** {F17371} The
10ae0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
10af0 75 73 65 64 28 29 20 72 6f 75 74 69 6e 65 20 72  used() routine r
10b00 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
10b10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
10b20 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
10b30 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
10b40 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
10b50 66 72 65 65 64 29 2e 0a 2a 2a 20 7b 46 31 37 33  freed)..** {F173
10b60 37 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72 65  72} The value re
10b70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
10b80 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 20  3_memory_used() 
10b90 69 6e 63 6c 75 64 65 73 0a 2a 2a 20 61 6e 79 20  includes.** any 
10ba0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
10bb0 79 20 53 51 4c 69 74 65 2c 20 62 75 74 20 6e 6f  y SQLite, but no
10bc0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
10bd0 20 62 79 20 74 68 65 0a 2a 2a 20 6c 69 62 72 61   by the.** libra
10be0 72 79 20 6d 61 6c 6c 6f 63 28 29 20 74 68 61 74  ry malloc() that
10bf0 20 62 61 63 6b 73 20 74 68 65 20 73 71 6c 69 74   backs the sqlit
10c00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  e3_malloc() impl
10c10 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 7b  ementation..** {
10c20 46 31 37 33 37 33 7d 20 54 68 65 20 73 71 6c 69  F17373} The sqli
10c30 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
10c40 61 74 65 72 28 29 20 72 6f 75 74 69 6e 65 73 20  ater() routines 
10c50 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6d  returns the.** m
10c60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
10c70 20 62 79 74 65 73 20 74 68 61 74 20 68 61 76 65   bytes that have
10c80 20 62 65 65 6e 20 6f 75 74 73 74 61 6e 64 69 6e   been outstandin
10c90 67 20 61 74 20 61 6e 79 20 74 69 6d 65 0a 2a 2a  g at any time.**
10ca0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 77   since the highw
10cb0 61 74 65 72 20 6d 61 72 6b 20 77 61 73 20 6c 61  ater mark was la
10cc0 73 74 20 72 65 73 65 74 2e 0a 2a 2a 20 7b 46 31  st reset..** {F1
10cd0 37 33 37 34 7d 20 54 68 65 20 62 79 74 65 20 63  7374} The byte c
10ce0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
10cf0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
10d00 68 69 67 68 77 61 74 65 72 28 29 0a 2a 2a 20 75  highwater().** u
10d10 73 65 73 20 74 68 65 20 73 61 6d 65 20 62 79 74  ses the same byt
10d20 65 20 63 6f 75 6e 74 69 6e 67 20 72 75 6c 65 73  e counting rules
10d30 20 61 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f   as sqlite3_memo
10d40 72 79 5f 75 73 65 64 28 29 2e 20 7b 45 4e 44 7d  ry_used(). {END}
10d50 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
10d60 64 73 2c 20 6f 76 65 72 68 65 61 64 20 61 64 64  ds, overhead add
10d70 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
10d80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 75 6e 74   SQLite is count
10d90 65 64 2c 0a 2a 2a 20 62 75 74 20 6f 76 65 72 68  ed,.** but overh
10da0 65 61 64 20 66 72 6f 6d 20 74 68 65 20 75 6e 64  ead from the und
10db0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6d  erlying system m
10dc0 61 6c 6c 6f 63 20 69 73 20 6e 6f 74 2e 0a 2a 2a  alloc is not..**
10dd0 20 7b 46 31 37 33 37 35 7d 20 49 66 20 74 68 65   {F17375} If the
10de0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
10df0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10e00 68 77 61 74 65 72 28 29 20 69 73 20 74 72 75 65  hwater() is true
10e10 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 68 69  ,.** then the hi
10e20 67 68 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  ghwater mark is 
10e30 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
10e40 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
10e50 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
10e60 75 73 65 64 28 29 20 61 6e 64 20 74 68 65 20 70  used() and the p
10e70 72 69 6f 72 20 68 69 67 68 77 61 74 65 72 20 6d  rior highwater m
10e80 61 72 6b 20 28 62 65 66 6f 72 65 20 74 68 65 0a  ark (before the.
10e90 2a 2a 20 72 65 73 65 74 29 20 69 73 20 72 65 74  ** reset) is ret
10ea0 75 72 6e 65 64 2e 20 20 7b 46 31 37 33 37 36 7d  urned.  {F17376}
10eb0 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
10ec0 65 72 20 74 6f 20 0a 2a 2a 20 73 71 6c 69 74 65  er to .** sqlite
10ed0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
10ee0 65 72 28 29 20 69 73 20 7a 65 72 6f 2c 20 74 68  er() is zero, th
10ef0 65 6e 20 74 68 65 20 68 69 67 68 77 61 74 65 72  en the highwater
10f00 20 6d 61 72 6b 20 69 73 0a 2a 2a 20 75 6e 63 68   mark is.** unch
10f10 61 6e 67 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65  anged..*/.sqlite
10f20 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
10f30 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
10f40 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
10f50 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
10f60 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
10f70 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
10f80 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
10f90 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
10fa0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
10fb0 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12500}.**.** {
10fc0 46 31 32 35 30 31 7d 20 54 68 69 73 20 72 6f 75  F12501} This rou
10fd0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
10fe0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
10ff0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
11000 69 63 75 6c 61 72 0a 2a 2a 20 64 61 74 61 62 61  icular.** databa
11010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 73  se connection, s
11020 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
11030 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 7b  irst argument. {
11040 46 31 32 35 30 32 7d 0a 2a 2a 20 54 68 65 20 61  F12502}.** The a
11050 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
11060 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
11070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
11080 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
11090 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
110a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
110b0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
110c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
110d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
110e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
110f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
11100 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 7b 46 31  re16_v2()].  {F1
11110 32 35 30 33 7d 20 41 74 20 76 61 72 69 6f 75 73  2503} At various
11120 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
11130 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
11140 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
11150 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
11160 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
11170 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
11180 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
11190 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
111a0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
111b0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
111c0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
111d0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
111e0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
111f0 2a 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  * return SQLITE_
11200 4f 4b 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  OK to allow the 
11210 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
11220 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
11230 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
11240 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
11250 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
11260 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
11270 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
11280 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
11290 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
112a0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
112b0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
112c0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
112d0 61 6e 20 65 72 72 6f 72 2e 20 20 7b 46 31 32 35  an error.  {F125
112e0 30 34 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  04} If the autho
112f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
11300 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
11310 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
11320 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
11330 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
11340 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
11350 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   then [sqlite3_p
11360 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
11370 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
11380 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
11390 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
113a0 20 73 68 61 6c 6c 0a 2a 2a 20 66 61 69 6c 20 77   shall.** fail w
113b0 69 74 68 20 61 6e 20 53 51 4c 49 54 45 5f 45 52  ith an SQLITE_ER
113c0 52 4f 52 20 65 72 72 6f 72 20 63 6f 64 65 20 61  ROR error code a
113d0 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
113e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
113f0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 57 68 65   {END}.**.** Whe
11400 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
11410 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
11420 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
11430 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
11440 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
11450 20 20 7b 46 31 32 35 30 35 7d 20 57 68 65 6e 20    {F12505} When 
11460 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
11470 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
11480 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
11490 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
114a0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
114b0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
114c0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
114d0 72 69 7a 65 72 20 73 68 61 6c 6c 20 66 61 69 6c  rizer shall fail
114e0 0a 2a 2a 20 77 69 74 68 20 61 6e 20 53 51 4c 49  .** with an SQLI
114f0 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72 20 63  TE_ERROR error c
11500 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ode and an error
11510 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
11520 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
11530 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 7b 46  ss is denied. {F
11540 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
11550 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
11560 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
11570 0a 2a 2a 20 74 6f 20 74 68 65 20 61 75 74 68 6f  .** to the autho
11580 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
11590 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
115a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
115b0 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 72  AD], then.** a r
115c0 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45  eturn of [SQLITE
115d0 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65  _IGNORE] has the
115e0 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
115f0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 20 0a  [SQLITE_DENY]. .
11600 2a 2a 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  ** If the author
11610 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51  izer code is [SQ
11620 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74  LITE_READ] and t
11630 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
11640 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
11650 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
11660 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11670 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
11680 64 20 74 6f 0a 2a 2a 20 69 6e 73 65 72 74 20 61  d to.** insert a
11690 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
116a0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
116b0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
116c0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
116d0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
116e0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
116f0 74 75 72 6e 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  turned. {END}.**
11700 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68 65  .** {F12510} The
11710 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11720 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
11730 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
11740 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
11750 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
11760 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
11770 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
11780 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 7b 46  interface..** {F
11790 31 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e  12511} The secon
117a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
117b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
117c0 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b 53  n integer .** [S
117d0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
117e0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
117f0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
11800 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
11810 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  * to be authoriz
11820 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20 61 76  ed. {END} The av
11830 61 69 6c 61 62 6c 65 20 61 63 74 69 6f 6e 20 63  ailable action c
11840 6f 64 65 73 20 61 72 65 0a 2a 2a 20 5b 53 51 4c  odes are.** [SQL
11850 49 54 45 5f 43 4f 50 59 20 7c 20 64 6f 63 75 6d  ITE_COPY | docum
11860 65 6e 74 65 64 20 73 65 70 61 72 61 74 65 6c 79  ented separately
11870 5d 2e 20 20 7b 46 31 32 35 31 32 7d 20 54 68 65  ].  {F12512} The
11880 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
11890 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ixth.** paramete
118a0 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
118b0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
118c0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
118d0 68 61 74 20 63 6f 6e 74 61 69 6e 20 0a 2a 2a 20  hat contain .** 
118e0 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
118f0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
11900 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
11910 69 7a 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ized. {END}.**.*
11920 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
11930 69 73 20 75 73 65 64 20 77 68 65 6e 20 70 72 65  is used when pre
11940 70 61 72 69 6e 67 20 53 51 4c 20 73 74 61 74 65  paring SQL state
11950 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
11960 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63  trusted.** sourc
11970 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
11980 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
11990 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20  ents do not try 
119a0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a  to access data.*
119b0 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  * that they are 
119c0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
119d0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
119e0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a   do not try to.*
119f0 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  * execute malici
11a00 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
11a10 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
11a20 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
11a30 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
11a40 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
11a50 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
11a60 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
11a70 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
11a80 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
11a90 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
11aa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
11ab0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
11ac0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
11ad0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
11ae0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
11af0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
11b00 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
11b10 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
11b20 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
11b30 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
11b40 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
11b50 6e 67 20 70 72 65 70 61 72 65 64 20 74 68 61 74  ng prepared that
11b60 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
11b70 74 68 69 6e 67 0a 2a 2a 20 65 78 63 65 70 74 20  thing.** except 
11b80 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
11b90 73 2e 20 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  s.  .**.** {F125
11ba0 32 30 7d 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  20} Only a singl
11bb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
11bc0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
11bd0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
11be0 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
11bf0 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
11c00 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
11c10 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
11c20 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
11c30 75 73 20 63 61 6c 6c 2e 20 7b 46 31 32 35 32 31  us call. {F12521
11c40 7d 20 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  }  A NULL author
11c50 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
11c60 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
11c70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
11c80 69 6e 76 6f 6b 65 64 2e 20 20 7b 46 31 32 35 32  invoked.  {F1252
11c90 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
11ca0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
11cb0 4c 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 4e  L. {END}.**.** N
11cc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
11cd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
11ce0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
11cf0 20 64 75 72 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c   during .** [sql
11d00 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
11d10 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
11d20 20 20 7b 46 31 32 35 32 33 7d 20 41 75 74 68 6f    {F12523} Autho
11d30 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
11d40 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
11d50 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
11d60 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
11d70 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 7b 45  ite3_step()]. {E
11d80 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ND}.*/.int sqlit
11d90 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
11da0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
11db0 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
11dc0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
11dd0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
11de0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
11df0 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
11e00 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
11e10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11e20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
11e30 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d  n Codes {F12590}
11e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
11e50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
11e60 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
11e70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
11e80 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
11e90 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
11ea0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
11eb0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
11ec0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
11ed0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
11ee0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
11ef0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
11f00 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
11f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
11f20 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
11f30 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
11f40 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
11f50 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
11f60 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
11f70 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
11f80 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
11f90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
11fa0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
11fb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
11fc0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
11fd0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
11fe0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
11ff0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
12000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12010 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
12020 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30  on Codes {F12550
12030 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  }.**.** The [sql
12040 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
12050 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
12060 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
12070 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
12080 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
12090 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 72 20  d to authorizer 
120a0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
120b0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
120c0 7b 46 31 32 35 35 31 7d 20 54 68 65 0a 2a 2a 20  {F12551} The.** 
120d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
120e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
120f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
12100 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
12110 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
12120 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
12130 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
12140 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
12150 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
12160 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
12170 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
12180 65 20 70 61 73 73 65 64 2e 20 7b 45 4e 44 7d 0a  e passed. {END}.
12190 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
121a0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
121b0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
121c0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
121d0 20 74 6f 20 62 65 20 0a 2a 2a 20 61 75 74 68 6f   to be .** autho
121e0 72 69 7a 65 64 2e 20 20 7b 46 31 32 35 35 32 7d  rized.  {F12552}
121f0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
12200 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
12210 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
12220 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
12230 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
12240 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
12250 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
12260 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
12270 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
12280 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
12290 6d 65 74 65 72 2e 20 7b 46 31 32 35 35 33 7d 20  meter. {F12553} 
122a0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
122b0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
122c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
122d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
122e0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
122f0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 0a 2a 2a  in", "temp", .**
12300 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
12310 61 62 6c 65 2e 20 7b 46 31 32 35 35 34 7d 20 54  able. {F12554} T
12320 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
12330 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
12340 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
12350 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
12360 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
12370 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
12380 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
12390 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
123a0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
123b0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
123c0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
123d0 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a 20 74  ectly from .** t
123e0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
123f0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
12400 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12410 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
12420 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
12430 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
12440 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
12450 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
12460 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
12470 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
12480 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
12490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
124a0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
124b0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
124c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
124d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
124e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
124f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
12500 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
12510 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
12520 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
12530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12540 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
12550 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
12560 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
12570 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
12580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12590 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
125a0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
125b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
125c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
125d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
125e0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
125f0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
12600 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
12610 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
12620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
12630 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
12640 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
12650 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
12660 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
12670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
12680 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
12690 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
126a0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
126b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
126c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
126d0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
126e0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
126f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
12700 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
12710 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
12720 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
12730 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
12740 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
12750 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
12760 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
12770 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
12780 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
12790 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
127a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
127b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
127c0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
127d0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
127e0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
127f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
12800 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
12810 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
12820 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
12830 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
12840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
12850 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
12860 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
12870 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
12880 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
12890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
128a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
128b0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
128c0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
128d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
128e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
128f0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
12900 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
12910 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
12920 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
12930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
12940 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
12950 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
12960 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
12970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
12980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12990 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
129a0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
129b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
129c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
129d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
129e0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
129f0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
12a00 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
12a10 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
12a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12a30 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
12a40 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
12a50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
12a60 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
12a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12a80 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
12a90 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
12aa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
12ab0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
12ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
12ad0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
12ae0 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c      22   /* NULL
12af0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
12b00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
12b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
12b20 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
12b30 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
12b40 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
12b50 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
12b60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
12b70 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
12b80 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
12b90 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
12ba0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
12bb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
12bc0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
12bd0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
12be0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
12bf0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
12c00 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
12c10 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
12c20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
12c30 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
12c40 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
12c50 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
12c60 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
12c70 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
12c80 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
12c90 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
12ca0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
12cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
12cc0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
12cd0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
12ce0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
12cf0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
12d00 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
12d10 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
12d20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
12d30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
12d40 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
12d50 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
12d60 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
12d70 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
12d80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
12d90 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
12da0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
12db0 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65  /* Function Name
12dc0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
12dd0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
12de0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
12df0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
12e00 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
12e10 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
12e20 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
12e30 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
12e40 69 6f 6e 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a  ions {F12280}.**
12e50 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12e60 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
12e70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
12e80 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
12e90 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
12ea0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
12eb0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
12ec0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
12ed0 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54 68 65  .** {F12281} The
12ee0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
12ef0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
12f00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
12f10 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
12f20 74 20 74 68 65 20 66 69 72 73 74 20 5b 73 71 6c  t the first [sql
12f30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
12f40 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
12f50 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
12f60 65 6e 74 2e 0a 2a 2a 20 7b 46 31 32 32 38 32 7d  ent..** {F12282}
12f70 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 74   Only a single t
12f80 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 63 61  race callback ca
12f90 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
12fa0 61 74 20 61 20 74 69 6d 65 2e 0a 2a 2a 20 45 61  at a time..** Ea
12fb0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
12fc0 65 33 5f 74 72 61 63 65 28 29 20 6f 76 65 72 72  e3_trace() overr
12fd0 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ides the previou
12fe0 73 2e 20 20 7b 46 31 32 32 38 33 7d 20 41 0a 2a  s.  {F12283} A.*
12ff0 2a 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 20  * NULL callback 
13000 66 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63  for sqlite3_trac
13010 65 28 29 20 64 69 73 61 62 6c 65 73 20 74 72 61  e() disables tra
13020 63 69 6e 67 2e 20 20 7b 46 31 32 32 38 34 7d 20  cing.  {F12284} 
13030 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  The.** first arg
13040 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
13050 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ce callback is a
13060 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69   copy of the poi
13070 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 77 61  nter which.** wa
13080 73 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  s the 3rd argume
13090 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72  nt to sqlite3_tr
130a0 61 63 65 2e 20 20 7b 46 31 32 32 38 35 7d 20 54  ace.  {F12285} T
130b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
130c0 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 74 72 61  nt.** to the tra
130d0 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ce callback is a
130e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
130f0 20 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e   UTF8 string con
13100 74 61 69 6e 69 6e 67 0a 2a 2a 20 74 68 65 20 6f  taining.** the o
13110 72 69 67 69 6e 61 6c 20 74 65 78 74 20 6f 66 20  riginal text of 
13120 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
13130 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
13140 65 64 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ed into.** [sqli
13150 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
13160 5d 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  ] or the equival
13170 65 6e 74 2e 20 7b 45 4e 44 7d 20 20 4e 6f 74 65  ent. {END}  Note
13180 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 68 6f 73   that the.** hos
13190 74 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  t parameter are 
131a0 6e 6f 74 20 65 78 70 61 6e 64 65 64 20 69 6e 20  not expanded in 
131b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
131c0 74 20 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  t text..**.** {F
131d0 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
131e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
131f0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
13200 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
13210 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
13220 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
13230 20 66 69 6e 69 73 68 65 73 2e 20 20 7b 46 31 32   finishes.  {F12
13240 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
13250 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
13260 2a 2a 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  ** profile callb
13270 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
13280 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
13290 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  er to sqlite3_pr
132a0 6f 66 69 6c 65 28 29 2e 0a 2a 2a 20 7b 46 31 32  ofile()..** {F12
132b0 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  289} The second 
132c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
132d0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
132e0 6b 20 69 73 20 61 0a 2a 2a 20 7a 65 72 6f 2d 74  k is a.** zero-t
132f0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
13300 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74  string that cont
13310 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  ains the complet
13320 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 74 68 65  e text of.** the
13330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
13340 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
13350 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
13360 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
13370 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  ** the equivalen
13380 74 2e 20 20 7b 46 31 32 32 39 30 7d 20 54 68 65  t.  {F12290} The
13390 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
133a0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
133b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  .** callback is 
133c0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
133d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
133e0 6f 73 65 63 6f 6e 64 73 20 6f 66 0a 2a 2a 20 77  oseconds of.** w
133f0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
13400 65 71 75 69 72 65 64 20 74 6f 20 72 75 6e 20 74  equired to run t
13410 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
13420 20 66 72 6f 6d 20 73 74 61 72 74 0a 2a 2a 20 74   from start.** t
13430 6f 20 66 69 6e 69 73 68 2e 20 7b 45 4e 44 7d 20  o finish. {END} 
13440 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
13450 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50  te3_profile() AP
13460 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  I is currently c
13470 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
13480 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73  mental and.** is
13490 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
134a0 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ge..*/.void *sql
134b0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
134c0 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
134d0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
134e0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  har*), void*);.v
134f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
13500 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
13510 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
13520 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
13530 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
13540 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
13550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
13560 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
13570 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d 0a  lbacks {F12910}.
13580 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54  **.** {F12911} T
13590 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
135a0 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
135b0 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
135c0 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
135d0 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
135e0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
135f0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
13600 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
13610 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
13620 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
13630 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
13640 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13650 65 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 41 6e 20  e()]. {END}  An 
13660 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
13670 74 68 69 73 20 0a 2a 2a 20 69 6e 74 65 72 66 61  this .** interfa
13680 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
13690 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
136a0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
136b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d  ..**.** {F12912}
136c0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
136d0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
136e0 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79  d once for every
136f0 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61   N virtual.** ma
13700 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
13710 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
13720 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13730 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
13740 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20  ** {F12913} The 
13750 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
13760 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  k itself is iden
13770 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
13780 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
13790 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
137a0 2e 20 7b 46 31 32 39 31 34 7d 20 54 68 65 20 66  . {F12914} The f
137b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
137c0 6f 20 74 68 69 73 0a 2a 2a 20 66 75 6e 63 74 69  o this.** functi
137d0 6f 6e 20 69 73 20 61 20 76 6f 69 64 20 70 6f 69  on is a void poi
137e0 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
137f0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
13800 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
13810 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73   each time it is
13820 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a   invoked. {END}.
13830 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49  **.** {F12915} I
13840 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
13850 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
13860 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
13870 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  or.** [sqlite3_g
13880 65 74 5f 74 61 62 6c 65 28 29 5d 20 72 65 73 75  et_table()] resu
13890 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
138a0 6e 20 4e 20 6f 70 63 6f 64 65 73 20 62 65 69 6e  n N opcodes bein
138b0 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a 20 74  g executed,.** t
138c0 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
138d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76   callback is nev
138e0 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b 45 4e 44  er invoked. {END
138f0 7d 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 32 39 31 36  }.** .** {F12916
13900 7d 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  } Only a single 
13910 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
13920 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
13930 65 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72  e registered for
13940 20 65 61 63 68 0a 2a 2a 20 6f 70 65 6e 20 64 61   each.** open da
13950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13960 6e 2e 20 20 45 76 65 72 79 20 63 61 6c 6c 20 74  n.  Every call t
13970 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
13980 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
13990 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 72  overwrites the r
139a0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 70 72  esults of the pr
139b0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 7b 46 31  evious call. {F1
139c0 32 39 31 37 7d 0a 2a 2a 20 54 6f 20 72 65 6d 6f  2917}.** To remo
139d0 76 65 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ve the progress 
139e0 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f 67 65 74  callback altoget
139f0 68 65 72 2c 20 70 61 73 73 20 4e 55 4c 4c 20 61  her, pass NULL a
13a00 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
13a10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
13a20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
13a30 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38 7d 20 49  **.** {F12918} I
13a40 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
13a50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
13a60 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74  a result other t
13a70 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 74  han 0, then.** t
13a80 68 65 20 63 75 72 72 65 6e 74 20 71 75 65 72 79  he current query
13a90 20 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20   is immediately 
13aa0 74 65 72 6d 69 6e 61 74 65 64 20 61 6e 64 20 61  terminated and a
13ab0 6e 79 20 64 61 74 61 62 61 73 65 20 63 68 61 6e  ny database chan
13ac0 67 65 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  ges.** rolled ba
13ad0 63 6b 2e 20 7b 46 31 32 39 31 39 7d 0a 2a 2a 20  ck. {F12919}.** 
13ae0 54 68 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 5b  The containing [
13af0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
13b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
13b10 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
13b20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 63  3_get_table()] c
13b30 61 6c 6c 20 72 65 74 75 72 6e 73 20 53 51 4c 49  all returns SQLI
13b40 54 45 5f 49 4e 54 45 52 52 55 50 54 2e 20 7b 45  TE_INTERRUPT. {E
13b50 4e 44 7d 20 20 54 68 69 73 20 66 65 61 74 75 72  ND}  This featur
13b60 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
13b70 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
13b80 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  o implement the 
13b90 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
13ba0 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67 72 65 73 73  on a.** progress
13bb0 20 64 69 61 6c 6f 67 20 62 6f 78 20 69 6e 20 61   dialog box in a
13bc0 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71   GUI..*/.void sq
13bd0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
13be0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13bf0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
13c00 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
13c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
13c20 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
13c30 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
13c40 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F12700}.**.** {
13c50 46 31 32 37 30 31 7d 20 54 68 65 73 65 20 72 6f  F12701} These ro
13c60 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
13c70 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
13c80 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 0a 2a  ile whose name.*
13c90 2a 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  * is given by th
13ca0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
13cb0 65 6e 74 2e 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ent..** {F12702}
13cc0 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
13cd0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
13ce0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
13cf0 2a 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  * for [sqlite3_o
13d00 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
13d10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
13d20 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
13d30 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
13d40 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71  te order for [sq
13d50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
13d60 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 6e 20  .** {F12703} An 
13d70 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
13d80 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6e  e is returned in
13d90 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a 2a 20   *ppDb, even.** 
13da0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
13db0 72 73 2e 20 20 7b 46 31 32 37 32 33 7d 20 28 45  rs.  {F12723} (E
13dc0 78 63 65 70 74 69 6f 6e 3a 20 69 66 20 53 51 4c  xception: if SQL
13dd0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a  ite is unable.**
13de0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
13df0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
13e00 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
13e10 2c 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 0a 2a 2a  , a NULL will.**
13e20 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
13e30 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
13e40 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
13e50 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
13e60 65 63 74 2e 29 0a 2a 2a 20 7b 46 31 32 37 30 34  ect.).** {F12704
13e70 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
13e80 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
13e90 2f 6f 72 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  /or created).** 
13ea0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
13eb0 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  en [SQLITE_OK] i
13ec0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31  s returned.  {F1
13ed0 32 37 30 35 7d 20 4f 74 68 65 72 77 69 73 65 20  2705} Otherwise 
13ee0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
13ef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 7b   is returned.  {
13f00 46 31 32 37 30 36 7d 20 54 68 65 0a 2a 2a 20 5b  F12706} The.** [
13f10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
13f20 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
13f30 72 6d 73 67 31 36 28 29 5d 20 20 72 6f 75 74 69  rmsg16()]  routi
13f40 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
13f50 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
13f60 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
13f70 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
13f80 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
13f90 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65   {F12707} The de
13fa0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
13fb0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
13fc0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
13fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
13fe0 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
13ff0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63  _open_v2()] is c
14000 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
14010 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
14020 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
14030 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14040 29 5d 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  )] is used..**.*
14050 2a 20 7b 46 31 32 37 30 38 7d 20 57 68 65 74 68  * {F12708} Wheth
14060 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
14070 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
14080 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
14090 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
140a0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 73  ated with the [s
140b0 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20  qlite3*] handle 
140c0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
140d0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 74  ed by passing it
140e0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
140f0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
14100 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
14110 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  quired..**.** {F
14120 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  12709} The [sqli
14130 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
14140 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
14150 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ike [sqlite3_ope
14160 6e 28 29 5d 20 0a 2a 2a 20 65 78 63 65 70 74 20  n()] .** except 
14170 74 68 61 74 20 69 74 20 61 63 63 63 65 70 74 73  that it acccepts
14180 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
14190 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
141a0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
141b0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
141c0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
141d0 63 74 69 6f 6e 2e 20 20 7b 46 31 32 37 31 30 7d  ction.  {F12710}
141e0 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   The flags param
141f0 65 74 65 72 20 63 61 6e 20 62 65 0a 2a 2a 20 6f  eter can be.** o
14200 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  ne of:.**.** <ol
14210 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
14220 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
14230 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
14240 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
14250 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  E].** <li>  [SQL
14260 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
14270 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
14280 45 4e 5f 43 52 45 41 54 45 5d 0a 2a 2a 20 3c 2f  EN_CREATE].** </
14290 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ol>.**.** {F1271
142a0 31 7d 20 54 68 65 20 66 69 72 73 74 20 76 61 6c  1} The first val
142b0 75 65 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74  ue opens the dat
142c0 61 62 61 73 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  abase read-only.
142d0 20 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49 66   .** {F12712} If
142e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
142f0 65 73 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  es not previousl
14300 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
14310 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
14320 2a 20 7b 46 31 32 37 31 33 7d 20 54 68 65 20 73  * {F12713} The s
14330 65 63 6f 6e 64 20 6f 70 74 69 6f 6e 20 6f 70 65  econd option ope
14340 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
14350 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
14360 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
14370 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
14380 6e 67 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 69 66  ng only if.** if
14390 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
143a0 74 65 20 70 72 6f 74 65 63 74 65 64 2e 20 20 7b  te protected.  {
143b0 46 31 32 37 31 34 7d 20 49 6e 20 65 69 74 68 65  F12714} In eithe
143c0 72 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  r case the datab
143d0 61 73 65 0a 2a 2a 20 6d 75 73 74 20 61 6c 72 65  ase.** must alre
143e0 61 64 79 20 65 78 69 73 74 20 6f 72 20 61 6e 20  ady exist or an 
143f0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
14400 64 2e 20 20 7b 46 31 32 37 31 35 7d 20 54 68 65  d.  {F12715} The
14410 20 74 68 69 72 64 20 6f 70 74 69 6f 6e 0a 2a 2a   third option.**
14420 20 6f 70 65 6e 73 20 74 68 65 20 64 61 74 61 62   opens the datab
14430 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
14440 61 6e 64 20 77 72 69 74 69 6e 67 20 61 6e 64 20  and writing and 
14450 63 72 65 61 74 65 73 20 69 74 20 69 66 20 69 74  creates it if it
14460 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 61 6c 72   does.** not alr
14470 65 61 64 79 20 65 78 69 73 74 2e 20 7b 46 31 32  eady exist. {F12
14480 37 31 36 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72  716}.** The thir
14490 64 20 6f 70 74 69 6f 6e 73 20 69 73 20 62 65 68  d options is beh
144a0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
144b0 77 61 79 73 20 75 73 65 64 20 66 6f 72 20 5b 73  ways used for [s
144c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
144d0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  * and [sqlite3_o
144e0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
144f0 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20  {F12717} If the 
14500 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
14510 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
14520 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d 65  private.** in-me
14530 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
14540 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
14550 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 7b 46 31   connection. {F1
14560 32 37 31 38 7d 20 54 68 69 73 20 69 6e 2d 6d 65  2718} This in-me
14570 6d 6f 72 79 0a 2a 2a 20 64 61 74 61 62 61 73 65  mory.** database
14580 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
14590 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
145a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
145b0 73 65 64 2e 20 7b 45 4e 44 7d 20 20 46 75 74 75  sed. {END}  Futu
145c0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  re.** version of
145d0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 6d 61   SQLite might ma
145e0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
145f0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
14600 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61 74 20 62  enames.** that b
14610 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
14620 22 20 63 68 61 72 61 63 74 65 72 2e 20 20 49 74  " character.  It
14630 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
14640 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e 20 61 20  that .** when a 
14650 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
14660 65 20 72 65 61 6c 6c 79 20 64 6f 65 73 20 62 65  e really does be
14670 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22 3a 22 20  gin with.** ":" 
14680 74 68 61 74 20 79 6f 75 20 70 72 65 66 69 78 20  that you prefix 
14690 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
146a0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 6c 69 6b  h a pathname lik
146b0 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20 61 76 6f  e "./" to.** avo
146c0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
146d0 0a 2a 2a 20 7b 46 31 32 37 31 39 7d 20 49 66 20  .** {F12719} If 
146e0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
146f0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
14700 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 20   then a private 
14710 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
14720 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
14730 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
14740 7b 46 31 32 37 32 30 7d 20 54 68 69 73 20 70 72  {F12720} This pr
14750 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
14760 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
14770 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
14780 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
14790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
147a0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
147b0 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65  .** {F12721} The
147c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
147d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
147e0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
147f0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
14800 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
14810 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
14820 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
14830 74 65 6d 20 0a 2a 2a 20 69 6e 74 65 72 66 61 63  tem .** interfac
14840 65 20 74 68 61 74 20 74 68 65 20 6e 65 77 20 64  e that the new d
14850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14860 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
14870 7b 46 31 32 37 32 32 7d 20 49 66 20 74 68 65 0a  {F12722} If the.
14880 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14890 74 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ter is a NULL po
148a0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
148b0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
148c0 76 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69  vfs].** object i
148d0 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  s used. {END}.**
148e0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 77  .** <b>Note to w
148f0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
14900 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
14910 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
14920 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
14930 2a 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * of [sqlite3_op
14940 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
14950 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6d 75  e3_open_v2()] mu
14960 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
14970 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
14980 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
14990 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
149a0 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
149b0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
149c0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
149d0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
149e0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
149f0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
14a00 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
14a10 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
14a20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a  te3_open_v2()]..
14a30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
14a40 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
14a50 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
14a60 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
14a70 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
14a80 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
14a90 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
14aa0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
14ab0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
14ac0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
14ad0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
14ae0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
14af0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
14b00 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
14b10 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
14b20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
14b30 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
14b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
14b50 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
14b60 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
14b70 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
14b80 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
14b90 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
14ba0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
14bb0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
14bc0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
14bd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
14be0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
14bf0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
14c00 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
14c10 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
14c20 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
14c30 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
14c40 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
14c50 73 20 7b 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a  s {F12800}.**.**
14c60 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20 73 71   {F12801} The sq
14c70 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
14c80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
14c90 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a  s the numeric.**
14ca0 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
14cb0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 53  sult code] or [S
14cc0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
14cd0 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
14ce0 6c 74 20 63 6f 64 65 5d 0a 2a 2a 20 66 6f 72 20  lt code].** for 
14cf0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
14d00 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
14d10 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
14d20 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 5b 73 71  ated.** with [sq
14d30 6c 69 74 65 33 5d 20 68 61 6e 64 6c 65 20 27 64  lite3] handle 'd
14d40 62 27 2e 20 7b 55 31 32 38 30 32 7d 20 49 66 20  b'. {U12802} If 
14d50 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
14d60 20 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a   failed but the.
14d70 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  ** most recent A
14d80 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
14d90 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
14da0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
14db0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73  _errcode().** is
14dc0 20 75 6e 64 65 66 69 6e 65 64 2e 20 7b 45 4e 44   undefined. {END
14dd0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 33 7d  }.**.** {F12803}
14de0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
14df0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
14e00 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
14e10 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
14e20 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
14e30 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
14e40 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
14e50 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 72   UTF8 or UTF16 r
14e60 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
14e70 7b 46 31 32 38 30 34 7d 20 4d 65 6d 6f 72 79 20  {F12804} Memory 
14e80 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
14e90 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
14ea0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
14eb0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 7b 55 31 32 38  rnally..** {U128
14ec0 30 35 7d 20 54 68 65 20 0a 2a 2a 20 73 74 72 69  05} The .** stri
14ed0 6e 67 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72  ng may be overwr
14ee0 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
14ef0 61 74 65 64 20 62 79 20 73 75 62 73 65 71 75 65  ated by subseque
14f00 6e 74 20 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69  nt calls to SQLi
14f10 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  te.** interface 
14f20 66 75 6e 63 74 69 6f 6e 73 2e 20 7b 45 4e 44 7d  functions. {END}
14f30 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 36 7d 20  .**.** {F12806} 
14f40 43 61 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71  Calls to many sq
14f50 6c 69 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e  lite3_* function
14f60 73 20 73 65 74 20 74 68 65 20 65 72 72 6f 72 20  s set the error 
14f70 63 6f 64 65 20 61 6e 64 0a 2a 2a 20 73 74 72 69  code and.** stri
14f80 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ng returned by [
14f90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
14fa0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
14fb0 6d 73 67 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  msg()], and.** [
14fc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
14fd0 28 29 5d 20 6f 76 65 72 77 72 69 74 69 6e 67 20  ()] overwriting 
14fe0 74 68 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c  the previous val
14ff0 75 65 73 2e 20 20 7b 46 31 32 38 30 37 7d 0a 2a  ues.  {F12807}.*
15000 2a 20 45 78 63 65 70 74 2c 20 63 61 6c 6c 73 20  * Except, calls 
15010 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
15020 6f 64 65 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ode()],.** [sqli
15030 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
15040 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
15050 73 67 31 36 28 29 5d 20 74 68 65 6d 73 65 6c 76  sg16()] themselv
15060 65 73 20 64 6f 20 6e 6f 74 20 61 66 66 65 63 74  es do not affect
15070 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 73 20   the.** results 
15080 6f 66 20 66 75 74 75 72 65 20 69 6e 76 6f 63 61  of future invoca
15090 74 69 6f 6e 73 2e 20 20 7b 46 31 32 38 30 38 7d  tions.  {F12808}
150a0 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
150b0 75 74 69 6e 65 73 20 74 68 61 74 0a 2a 2a 20 64  utines that.** d
150c0 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20  o not return an 
150d0 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
150e0 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
150f0 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
15100 6e 6f 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  not.** change th
15110 65 20 65 72 72 6f 72 20 63 6f 64 65 20 72 65 74  e error code ret
15120 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
15130 75 74 69 6e 65 2e 20 20 7b 46 31 32 38 30 39 7d  utine.  {F12809}
15140 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   Interfaces that
15150 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 61 73 73 6f  .** are not asso
15160 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70  ciated with a sp
15170 65 63 69 66 69 63 20 64 61 74 61 62 61 73 65 20  ecific database 
15180 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 65 78 61 6d  connection (exam
15190 70 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c 69 74 65  ples:.** [sqlite
151a0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
151b0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
151c0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 20  shared_cache()] 
151d0 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a  do not change.**
151e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
151f0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46  . {END}.**.** {F
15200 31 32 38 31 30 7d 20 41 73 73 75 6d 69 6e 67 20  12810} Assuming 
15210 6e 6f 20 6f 74 68 65 72 20 69 6e 74 65 72 76 65  no other interve
15220 6e 69 6e 67 20 73 71 6c 69 74 65 33 5f 2a 20 41  ning sqlite3_* A
15230 50 49 20 63 61 6c 6c 73 20 61 72 65 20 6d 61 64  PI calls are mad
15240 65 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  e,.** the error 
15250 63 6f 64 65 20 72 65 74 75 72 6e 65 64 20 62 79  code returned by
15260 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
15270 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
15280 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 65 72  h the same.** er
15290 72 6f 72 20 61 73 20 74 68 65 20 73 74 72 69 6e  ror as the strin
152a0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
152b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
152c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
152d0 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
152e0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
152f0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
15300 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
15310 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
15320 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
15330 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
15340 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
15350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15360 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
15370 6a 65 63 74 20 7b 46 31 33 30 30 30 7d 0a 2a 2a  ject {F13000}.**
15380 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
15390 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
153a0 65 70 72 65 73 65 6e 74 20 73 69 6e 67 6c 65 20  epresent single 
153b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
153c0 20 54 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   This.** object 
153d0 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
153e0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
153f0 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
15400 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20  a .** "compiled 
15410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
15420 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
15430 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 20 0a 2a  tatement"..** .*
15440 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
15450 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
15460 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
15470 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
15480 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
15490 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
154a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
154b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
154c0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
154d0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
154e0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
154f0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
15500 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  rs using.**     
15510 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
15520 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
15530 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63 65 73 5d  nd_* interfaces]
15540 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
15550 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
15560 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
15570 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
15580 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
15590 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
155a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
155b0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
155c0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
155d0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
155e0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
155f0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
15600 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
15610 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15620 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
15630 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
15640 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
15650 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
15660 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
15670 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
15680 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
15690 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
156a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
156b0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
156c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
156d0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
156e0 74 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a  tement {F13010}.
156f0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
15700 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
15710 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
15720 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
15730 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
15740 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
15750 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
15760 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31  . .**.** {F13011
15770 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
15780 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e 20  ment "db" is an 
15790 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69 74  [sqlite3 | SQLit
157a0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
157b0 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  e] .** obtained 
157c0 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61 6c  from a prior cal
157d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
157e0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
157f0 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  open_v2()].** or
15800 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
15810 28 29 5d 2e 20 7b 46 31 33 30 31 32 7d 0a 2a 2a  ()]. {F13012}.**
15820 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
15830 6d 65 6e 74 20 22 7a 53 71 6c 22 20 69 73 20 74  ment "zSql" is t
15840 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
15850 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
15860 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
15870 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
15880 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
15890 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
158a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
158b0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
158c0 20 75 73 65 73 20 55 54 46 2d 38 20 61 6e 64 20   uses UTF-8 and 
158d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
158e0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
158f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
15900 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 20 7b 45  * use UTF-16. {E
15910 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  ND}.**.** {F1301
15920 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  3} If the nByte 
15930 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
15940 0a 2a 2a 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  .** than zero, t
15950 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
15960 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
15970 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
15980 2e 0a 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66  ..** {F13014} If
15990 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
159a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
159b0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  is the maximum n
159c0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79 74  umber of .** byt
159d0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
159e0 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69  l.  When nByte i
159f0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
15a00 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
15a10 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
15a20 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
15a30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
15a40 68 61 72 61 63 74 65 72 20 6f 72 20 0a 2a 2a 20  haracter or .** 
15a50 75 6e 74 69 6c 20 74 68 65 20 6e 42 79 74 65 2d  until the nByte-
15a60 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
15a70 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
15a80 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  {END}.**.** {F13
15a90 30 31 35 7d 20 2a 70 7a 54 61 69 6c 20 69 73 20  015} *pzTail is 
15aa0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
15ab0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
15ac0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
15ad0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c  the.** first SQL
15ae0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
15af0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
15b00 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65  nes only compile
15b10 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73  s the first.** s
15b20 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
15b30 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
15b40 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
15b50 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a   what remains.**
15b60 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 20 7b 45 4e   uncompiled. {EN
15b70 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36  D}.**.** {F13016
15b80 7d 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66  } *ppStmt is lef
15b90 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
15ba0 63 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b 73 71  compiled .** [sq
15bb0 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c  lite3_stmt | SQL
15bc0 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72 75 63   statement struc
15bd0 74 75 72 65 5d 20 74 68 61 74 20 63 61 6e 20 62  ture] that can b
15be0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
15bf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
15c00 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74 68 65  p()].  Or if the
15c10 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
15c20 2a 70 70 53 74 6d 74 20 6d 61 79 20 62 65 0a 2a  *ppStmt may be.*
15c30 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 20 20  * set to NULL.  
15c40 7b 46 31 33 30 31 37 7d 20 49 66 20 74 68 65 20  {F13017} If the 
15c50 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
15c60 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
15c70 68 65 20 69 6e 70 75 74 0a 2a 2a 20 69 73 20 61  he input.** is a
15c80 6e 64 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  nd empty string 
15c90 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
15ca0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
15cb0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55  t to NULL..** {U
15cc0 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69  13018} The calli
15cd0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
15ce0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
15cf0 64 65 6c 65 74 69 6e 67 20 74 68 65 0a 2a 2a 20  deleting the.** 
15d00 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
15d10 74 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20  tement.** using 
15d20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
15d30 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
15d40 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
15d50 69 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  it..**.** {F1301
15d60 39 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  9} On success, [
15d70 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
15d80 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
15d90 73 65 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  se an .** [SQLIT
15da0 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20  E_ERROR | error 
15db0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
15dc0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  d. {END}.**.** T
15dd0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
15de0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
15df0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
15e00 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
15e10 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
15e20 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
15e30 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
15e40 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
15e50 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
15e60 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15e70 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
15e80 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
15e90 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 7b 46  scouraged..** {F
15ea0 31 33 30 32 30 7d 20 49 6e 20 74 68 65 20 22 76  13020} In the "v
15eb0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
15ec0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
15ed0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
15ee0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
15ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
15f00 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
15f10 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a   copy of the .**
15f20 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
15f30 78 74 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63  xt. {END} This c
15f40 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
15f50 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
15f60 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
15f70 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20  e a differently 
15f80 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a  in two ways:.**.
15f90 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 7b  ** <ol>.** <li>{
15fa0 46 31 33 30 32 32 7d 0a 2a 2a 20 49 66 20 74 68  F13022}.** If th
15fb0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
15fc0 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65  a changes, inste
15fd0 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20  ad of returning 
15fe0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
15ff0 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20  as it.** always 
16000 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c  used to do, [sql
16010 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
16020 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
16030 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51  recompile the SQ
16040 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  L.** statement a
16050 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74  nd try to run it
16060 20 61 67 61 69 6e 2e 20 7b 46 31 32 30 32 33 7d   again. {F12023}
16070 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68   If the schema h
16080 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a  as changed in.**
16090 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65   a way that make
160a0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
160b0 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c  no longer valid,
160c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
160d0 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20  ] will still.** 
160e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53  return [SQLITE_S
160f0 43 48 45 4d 41 5d 2e 20 20 7b 45 4e 44 7d 20 42  CHEMA].  {END} B
16100 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
16110 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 0a  gacy behavior, .
16120 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ** [SQLITE_SCHEM
16130 41 5d 20 69 73 20 6e 6f 77 20 61 20 66 61 74 61  A] is now a fata
16140 6c 20 65 72 72 6f 72 2e 20 20 7b 46 31 32 30 32  l error.  {F1202
16150 34 7d 20 43 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73  4} Calling.** [s
16160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
16170 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
16180 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
16190 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
161a0 7b 46 31 32 30 32 35 7d 20 4e 6f 74 65 3a 20 75  {F12025} Note: u
161b0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
161c0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
161d0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
161e0 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
161f0 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
16200 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
16210 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a  ] return. {END}.
16220 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
16230 6c 69 3e 0a 2a 2a 20 7b 46 31 33 30 33 30 7d 20  li>.** {F13030} 
16240 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
16250 63 75 72 73 2c 20 0a 2a 2a 20 5b 73 71 6c 69 74  curs, .** [sqlit
16260 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
16270 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
16280 65 20 64 65 74 61 69 6c 65 64 20 0a 2a 2a 20 5b  e detailed .** [
16290 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
162a0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
162b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
162c0 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
162d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20   result codes]. 
162e0 20 7b 46 31 33 30 33 31 7d 0a 2a 2a 20 54 68 65   {F13031}.** The
162f0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
16300 20 77 61 73 20 74 68 61 74 20 5b 73 71 6c 69 74   was that [sqlit
16310 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
16320 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
16330 65 6e 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54  eneric.** [SQLIT
16340 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
16350 63 6f 64 65 20 61 6e 64 20 79 6f 75 20 77 6f 75  code and you wou
16360 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
16370 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
16380 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
16390 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  et()] in order t
163a0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
163b0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
163c0 68 65 20 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 7b  he problem..** {
163d0 46 31 33 30 33 32 7d 0a 2a 2a 20 57 69 74 68 20  F13032}.** With 
163e0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
163f0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
16400 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
16410 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
16420 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20   is.** returned 
16430 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 7b 45 4e  immediately. {EN
16440 44 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  D}.** </li>.** <
16450 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
16460 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
16470 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
16480 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
16490 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
164a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
164b0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
164c0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
164d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
164e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
164f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
16500 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
16510 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
16520 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
16530 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
16540 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
16550 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
16560 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
16570 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
16580 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
16590 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
165a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
165b0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
165c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
165d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
165e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
165f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
16600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
16610 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
16620 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
16630 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
16640 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
16650 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
16660 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
16670 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
16680 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
16690 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
166a0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
166b0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
166c0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
166d0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
166e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
166f0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
16700 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
16710 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
16720 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
16730 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
16740 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
16750 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
16760 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
16770 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
16780 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
16790 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
167a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
167b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
167c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
167d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
167e0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
167f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
16800 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
16810 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
16820 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
16830 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
16840 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
16850 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
16860 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
16870 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
16880 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
16890 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
168a0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
168b0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
168c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
168d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
168e0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
168f0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
16900 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
16910 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
16920 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
16930 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
16940 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
16950 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
16960 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
16970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20  ./*.** CAPIREF: 
16980 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
16990 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30  ment SQL {F13100
169a0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  }.**.** {F13101}
169b0 20 49 66 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   If the compiled
169c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 70   SQL statement p
169d0 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67 75  assed as an argu
169e0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
169f0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
16a00 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
16a10 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
16a20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
16a30 32 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  2()],.** then th
16a40 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
16a50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16a60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
16a70 65 64 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e  ed string.** con
16a80 74 61 69 6e 69 6e 67 20 61 20 63 6f 70 79 20 6f  taining a copy o
16a90 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53  f the original S
16aa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 7b 46  QL statement. {F
16ab0 31 33 31 30 32 7d 20 54 68 65 0a 2a 2a 20 70 6f  13102} The.** po
16ac0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
16ad0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
16ae0 6e 74 0a 2a 2a 20 69 73 20 64 65 6c 65 74 65 64  nt.** is deleted
16af0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
16b00 69 6e 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 7b 46  inalize()..** {F
16b10 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
16b20 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
16b30 6c 69 74 65 33 5f 73 71 6c 28 29 20 69 73 20 61  lite3_sql() is a
16b40 6c 77 61 79 73 20 55 54 46 38 20 65 76 65 6e 0a  lways UTF8 even.
16b50 2a 2a 20 69 66 20 61 20 55 54 46 31 36 20 73 74  ** if a UTF16 st
16b60 72 69 6e 67 20 77 61 73 20 6f 72 69 67 69 6e 61  ring was origina
16b70 6c 6c 79 20 65 6e 74 65 72 65 64 20 75 73 69 6e  lly entered usin
16b80 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
16b90 72 65 31 36 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72  re16_v2()].** or
16ba0 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e   the equivalent.
16bb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 34 7d 20  .**.** {F13104} 
16bc0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
16bd0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
16be0 69 6e 67 20 65 69 74 68 65 72 20 6f 66 20 74 68  ing either of th
16bf0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
16c00 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
16c10 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
16c20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
16c30 28 29 5d 2c 20 74 68 69 73 0a 2a 2a 20 66 75 6e  ()], this.** fun
16c40 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 4e 55  ction returns NU
16c50 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  LL..*/.const cha
16c60 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
16c70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
16c80 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
16c90 33 52 45 46 3a 20 20 44 79 6e 61 6d 69 63 61 6c  3REF:  Dynamical
16ca0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
16cb0 62 6a 65 63 74 20 20 7b 46 31 35 30 30 30 7d 0a  bject  {F15000}.
16cc0 2a 2a 0a 2a 2a 20 7b 46 31 35 30 30 31 7d 20 53  **.** {F15001} S
16cd0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
16ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
16cf0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
16d00 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
16d10 68 61 74 20 61 72 65 20 6f 72 20 63 61 6e 20 62  hat are or can b
16d20 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
16d30 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 7b 45  tabase table. {E
16d40 4e 44 7d 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  ND}.** SQLite us
16d50 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
16d60 67 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  g for the values
16d70 20 69 74 20 73 74 6f 72 65 73 2e 20 20 0a 2a 2a   it stores.  .**
16d80 20 7b 46 31 35 30 30 32 7d 20 56 61 6c 75 65 73   {F15002} Values
16d90 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
16da0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
16db0 20 63 61 6e 20 62 65 0a 2a 2a 20 62 65 20 69 6e   can be.** be in
16dc0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
16dd0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
16de0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
16df0 72 20 4e 55 4c 4c 2e 0a 2a 2f 0a 74 79 70 65 64  r NULL..*/.typed
16e00 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
16e10 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
16e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
16e30 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
16e40 65 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30  ext Object {F160
16e50 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  01}.**.** The co
16e60 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
16e70 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
16e80 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
16e90 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
16ea0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
16eb0 74 2e 20 20 7b 46 31 36 30 30 32 7d 20 41 20 70  t.  {F16002} A p
16ec0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
16ed0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 20  ite3_context.** 
16ee0 6f 62 6a 65 63 74 20 69 73 20 61 6c 77 61 79 73  object is always
16ef0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16f00 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
16f10 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
16f20 74 69 6f 6e 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  tions..*/.typede
16f30 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
16f40 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
16f50 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
16f60 20 43 41 50 49 33 52 45 46 3a 20 20 42 69 6e 64   CAPI3REF:  Bind
16f70 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
16f80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
16f90 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 0a 2a 2a  s {F13500}.**.**
16fa0 20 7b 46 31 33 35 30 31 7d 20 49 6e 20 74 68 65   {F13501} In the
16fb0 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
16fc0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
16fd0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
16fe0 20 69 74 73 0a 2a 2a 20 76 61 72 69 61 6e 74 73   its.** variants
16ff0 2c 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  , literals may b
17000 65 20 72 65 70 6c 61 63 65 20 62 79 20 61 20 70  e replace by a p
17010 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 0a  arameter in one.
17020 2a 2a 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d  ** of these form
17030 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
17040 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
17050 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
17060 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 40 41  :AAA.** <li>  @A
17070 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  AA.** <li>  $VVV
17080 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
17090 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
170a0 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
170b0 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
170c0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
170d0 20 41 41 41 20 69 73 20 61 6e 20 61 6c 70 68 61   AAA is an alpha
170e0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
170f0 65 72 20 61 6e 64 20 56 56 56 20 69 73 20 61 20  er and VVV is a 
17100 76 61 72 69 61 62 6c 65 20 6e 61 6d 65 20 61 63  variable name ac
17110 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  cording.** to th
17120 65 20 73 79 6e 74 61 78 20 72 75 6c 65 73 20 6f  e syntax rules o
17130 66 20 74 68 65 20 54 43 4c 20 70 72 6f 67 72 61  f the TCL progra
17140 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67 65 2e 20  mming language. 
17150 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 76 61 6c  {END}.** The val
17160 75 65 73 20 6f 66 20 74 68 65 73 65 20 70 61 72  ues of these par
17170 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
17180 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
17190 65 74 65 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20  eter names").** 
171a0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
171b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
171c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
171d0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
171e0 2a 2a 20 7b 46 31 33 35 30 32 7d 20 54 68 65 20  ** {F13502} The 
171f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
17200 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
17210 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
17220 61 6c 77 61 79 73 0a 2a 2a 20 69 73 20 61 20 70  always.** is a p
17230 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
17240 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
17250 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
17260 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
17270 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
17280 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 7b 46  ts variants.  {F
17290 31 33 35 30 33 7d 20 54 68 65 20 73 65 63 6f 6e  13503} The secon
172a0 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  d.** argument is
172b0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
172c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  e parameter to b
172d0 65 20 73 65 74 2e 20 20 7b 46 31 33 35 30 34 7d  e set.  {F13504}
172e0 20 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 70 61   The.** first pa
172f0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
17300 6e 64 65 78 20 6f 66 20 31 2e 20 20 7b 46 31 33  ndex of 1.  {F13
17310 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 73 61  505} When the sa
17320 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 70 61 72 61  me named.** para
17330 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
17340 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
17350 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
17360 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
17370 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
17380 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
17390 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 20  rst occurrence. 
173a0 0a 2a 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65  .** {F13506} The
173b0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
173c0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
173d0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
173e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
173f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
17400 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66  r_name()] API if
17410 20 64 65 73 69 72 65 64 2e 20 20 7b 46 31 33 35   desired.  {F135
17420 30 37 7d 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  07} The index.**
17430 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
17440 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
17450 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 7b  lue of NNN..** {
17460 46 31 33 35 30 38 7d 20 54 68 65 20 4e 4e 4e 20  F13508} The NNN 
17470 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
17480 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
17490 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
174a0 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45  parameter SQLITE
174b0 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
174c0 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76 61  MBER (default va
174d0 6c 75 65 3a 20 39 39 39 29 2e 20 7b 45 4e 44 7d  lue: 999). {END}
174e0 0a 2a 2a 20 53 65 65 20 3c 61 20 68 72 65 66 3d  .** See <a href=
174f0 22 6c 69 6d 69 74 73 2e 68 74 6d 6c 22 3e 6c 69  "limits.html">li
17500 6d 69 74 73 2e 68 74 6d 6c 3c 2f 61 3e 20 66 6f  mits.html</a> fo
17510 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
17520 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
17530 7b 46 31 33 35 30 39 7d 20 54 68 65 20 74 68 69  {F13509} The thi
17540 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
17550 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
17560 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
17570 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  r. {END}.**.** {
17580 46 31 33 35 31 30 7d 20 49 6e 20 74 68 6f 73 65  F13510} In those
17590 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
175a0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
175b0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
175c0 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65  lue is the numbe
175d0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e  r of bytes.** in
175e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
175f0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
17600 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e  e value is the n
17610 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
17620 6e 20 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c  n the.** string,
17630 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
17640 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 20 7b  of characters. {
17650 46 31 33 35 31 31 7d 20 20 54 68 65 20 6e 75 6d  F13511}  The num
17660 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
17670 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17680 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
17690 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 20  ator at the end 
176a0 6f 66 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b  of strings..** {
176b0 46 31 33 35 31 32 7d 0a 2a 2a 20 49 66 20 74 68  F13512}.** If th
176c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
176d0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
176e0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
176f0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 6e  e string is.** n
17700 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
17710 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
17720 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
17730 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  {END}.**.** {F13
17740 35 31 33 7d 0a 2a 2a 20 54 68 65 20 66 69 66 74  513}.** The fift
17750 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
17760 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
17770 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
17780 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
17790 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
177a0 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
177b0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
177c0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
177d0 20 6f 72 0a 2a 2a 20 74 65 78 74 20 61 66 74 65   or.** text afte
177e0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
177f0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 7b  ished with it. {
17800 46 31 33 35 31 34 7d 20 49 66 20 74 68 65 20 66  F13514} If the f
17810 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
17820 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
17830 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
17840 41 54 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20  ATIC], then the 
17850 6c 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20  library assumes 
17860 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
17870 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
17880 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
17890 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
178a0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
178b0 65 65 64 2e 0a 2a 2a 20 7b 46 31 33 35 31 35 7d  eed..** {F13515}
178c0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
178d0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
178e0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
178f0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
17900 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
17910 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
17920 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
17930 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
17940 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
17950 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
17960 6e 65 20 72 65 74 75 72 6e 73 2e 20 7b 45 4e 44  ne returns. {END
17970 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 30 7d  }.**.** {F13520}
17980 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
17990 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
179a0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
179b0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
179c0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
179d0 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 7b 46 31  with zeros.  {F1
179e0 33 35 32 31 7d 20 41 20 7a 65 72 6f 62 6c 6f 62  3521} A zeroblob
179f0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
17a00 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
17a10 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
17a20 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69  er to hold it si
17a30 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
17a40 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
17a50 20 7b 45 4e 44 7d 0a 2a 2a 20 5a 65 72 6f 62 6c   {END}.** Zerobl
17a60 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
17a70 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
17a80 63 65 2d 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  ce-holders for B
17a90 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
17aa0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
17ab0 72 69 74 74 65 6e 20 75 73 69 6e 67 20 0a 2a 2a  ritten using .**
17ac0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
17ad0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 20  pen | increment 
17ae0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
17af0 65 73 2e 20 7b 46 31 33 35 32 32 7d 20 41 20 6e  es. {F13522} A n
17b00 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75 65  egative.** value
17b10 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
17b20 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
17b30 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
17b40 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
17b50 33 35 33 30 7d 20 54 68 65 20 73 71 6c 69 74 65  3530} The sqlite
17b60 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
17b70 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
17b80 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
17b90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17ba0 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
17bb0 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
17bc0 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
17bd0 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
17be0 33 5f 73 74 65 70 28 29 5d 2e 20 7b 46 31 33 35  3_step()]. {F135
17bf0 33 31 7d 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  31}.** Bindings 
17c00 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
17c10 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
17c20 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
17c30 2e 0a 2a 2a 20 7b 46 31 33 35 33 32 7d 20 55 6e  ..** {F13532} Un
17c40 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
17c50 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
17c60 20 61 73 20 4e 55 4c 4c 2e 20 7b 45 4e 44 7d 0a   as NULL. {END}.
17c70 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 30 7d 20 54  **.** {F13540} T
17c80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17c90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
17ca0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
17cb0 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a  n error code if.
17cc0 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  ** anything goes
17cd0 20 77 72 6f 6e 67 2e 20 20 7b 46 31 33 35 34 31   wrong.  {F13541
17ce0 7d 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d  } [SQLITE_RANGE]
17cf0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
17d00 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
17d10 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
17d20 20 72 61 6e 67 65 2e 20 20 7b 46 31 33 35 34 32   range.  {F13542
17d30 7d 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  } [SQLITE_NOMEM]
17d40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
17d50 6d 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a  malloc fails..**
17d60 20 7b 46 31 33 35 34 33 7d 20 5b 53 51 4c 49 54   {F13543} [SQLIT
17d70 45 5f 4d 49 53 55 53 45 5d 20 69 73 20 72 65 74  E_MISUSE] is ret
17d80 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
17d90 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
17da0 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
17db0 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
17dc0 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
17dd0 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
17de0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
17df0 61 6c 69 7a 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  alized..*/.int s
17e00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
17e10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
17e20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
17e30 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
17e40 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
17e50 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
17e60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
17e70 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
17e80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
17e90 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
17ea0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
17eb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
17ec0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
17ed0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
17ee0 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
17ef0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
17f00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
17f10 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
17f20 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
17f30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
17f40 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
17f50 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
17f60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
17f70 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
17f80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
17f90 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
17fa0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
17fb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
17fc0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
17fd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
17fe0 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
17ff0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
18000 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
18010 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
18020 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
18030 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
18040 72 20 4f 66 20 48 6f 73 74 20 50 61 72 61 6d 65  r Of Host Parame
18050 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
18060 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 52 65 74  .** {F13601} Ret
18070 75 72 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  urn the largest 
18080 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  host parameter i
18090 6e 64 65 78 20 69 6e 20 74 68 65 20 70 72 65 63  ndex in the prec
180a0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 73 74 61 74 65  ompiled.** state
180b0 6d 65 6e 74 20 67 69 76 65 6e 20 61 73 20 74 68  ment given as th
180c0 65 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 33  e argument. {F13
180d0 36 30 32 7d 20 57 68 65 6e 20 74 68 65 20 68 6f  602} When the ho
180e0 73 74 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  st parameters.**
180f0 20 61 72 65 20 6f 66 20 74 68 65 20 66 6f 72 6d   are of the form
18100 73 20 6c 69 6b 65 20 22 3a 41 41 41 22 2c 20 22  s like ":AAA", "
18110 24 56 56 56 22 2c 20 22 40 41 41 41 22 2c 20 6f  $VVV", "@AAA", o
18120 72 20 22 3f 22 2c 0a 2a 2a 20 74 68 65 6e 20 74  r "?",.** then t
18130 68 65 79 20 61 72 65 20 61 73 73 69 67 6e 65 64  hey are assigned
18140 20 73 65 71 75 65 6e 74 69 61 6c 20 69 6e 63 72   sequential incr
18150 65 61 73 69 6e 67 20 6e 75 6d 62 65 72 73 20 62  easing numbers b
18160 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 77 69 74 68  eginning.** with
18170 20 6f 6e 65 2c 20 73 6f 20 74 68 65 20 76 61 6c   one, so the val
18180 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
18190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  he number of par
181a0 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 7b 46 31 33  ameters..** {F13
181b0 36 30 33 7d 20 48 6f 77 65 76 65 72 0a 2a 2a 20  603} However.** 
181c0 69 66 20 74 68 65 20 73 61 6d 65 20 68 6f 73 74  if the same host
181d0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 20   parameter name 
181e0 69 73 20 75 73 65 64 20 6d 75 6c 74 69 70 6c 65  is used multiple
181f0 20 74 69 6d 65 73 2c 20 65 61 63 68 20 6f 63 63   times, each occ
18200 75 72 72 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69  urrance.** is gi
18210 76 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 75 6d  ven the same num
18220 62 65 72 2c 20 73 6f 20 74 68 65 20 76 61 6c 75  ber, so the valu
18230 65 20 72 65 74 75 72 6e 65 64 20 69 6e 20 74 68  e returned in th
18240 61 74 20 63 61 73 65 20 69 73 20 74 68 65 20 6e  at case is the n
18250 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71  umber.** of uniq
18260 75 65 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ue host paramete
18270 72 20 6e 61 6d 65 73 2e 20 7b 46 31 33 36 30 34  r names. {F13604
18280 7d 20 49 66 20 68 6f 73 74 20 70 61 72 61 6d 65  } If host parame
18290 74 65 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  ters of the.** f
182a0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 61 72 65 20 75  orm "?NNN" are u
182b0 73 65 64 20 28 77 68 65 72 65 20 4e 4e 4e 20 69  sed (where NNN i
182c0 73 20 61 6e 20 69 6e 74 65 67 65 72 29 20 74 68  s an integer) th
182d0 65 6e 20 74 68 65 72 65 20 6d 69 67 68 74 20 62  en there might b
182e0 65 0a 2a 2a 20 67 61 70 73 20 69 6e 20 74 68 65  e.** gaps in the
182f0 20 6e 75 6d 62 65 72 69 6e 67 20 61 6e 64 20 74   numbering and t
18300 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18310 64 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  d by this interf
18320 61 63 65 20 69 73 0a 2a 2a 20 74 68 65 20 69 6e  ace is.** the in
18330 64 65 78 20 6f 66 20 74 68 65 20 68 6f 73 74 20  dex of the host 
18340 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 74  parameter with t
18350 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
18360 20 76 61 6c 75 65 2e 20 7b 45 4e 44 7d 0a 2a 2a   value. {END}.**
18370 0a 2a 2a 20 7b 55 31 33 36 30 35 7d 20 54 68 65  .** {U13605} The
18380 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
18390 65 6e 74 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ent must not be 
183a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
183b0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 0a 2a  e | finalized].*
183c0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 69 73 20  * prior to this 
183d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 69 6e  routine returnin
183e0 67 2e 20 20 4f 74 68 65 72 77 69 73 65 20 74 68  g.  Otherwise th
183f0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
18400 64 65 66 69 6e 65 64 0a 2a 2a 20 61 6e 64 20 70  defined.** and p
18410 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
18420 62 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ble..*/.int sqli
18430 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
18440 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
18450 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
18460 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
18470 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
18480 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a  er {F13620}.**.*
18490 2a 20 7b 46 31 33 36 32 31 7d 20 54 68 69 73 20  * {F13621} This 
184a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
184b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
184c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
184d0 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  h.** parameter i
184e0 6e 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  n a [sqlite3_stm
184f0 74 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61  t | prepared sta
18500 74 65 6d 65 6e 74 5d 2e 20 7b 46 31 33 36 32 32  tement]. {F13622
18510 7d 0a 2a 2a 20 48 6f 73 74 20 70 61 72 61 6d 65  }.** Host parame
18520 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
18530 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
18540 22 20 6f 72 20 22 24 56 56 56 22 20 68 61 76 65  " or "$VVV" have
18550 20 61 20 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68   a name.** which
18560 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
18570 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
18580 6f 72 20 22 24 56 56 56 22 2e 20 0a 2a 2a 20 49  or "$VVV". .** I
18590 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
185a0 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
185b0 72 20 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20  r "$" or "@".** 
185c0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
185d0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
185e0 20 20 7b 46 31 33 36 32 36 7d 0a 2a 2a 20 50 61    {F13626}.** Pa
185f0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
18600 66 6f 72 6d 20 22 3f 22 20 6f 72 20 22 3f 4e 4e  form "?" or "?NN
18610 4e 22 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 2e  N" have no name.
18620 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 33 7d 20  .**.** {F13623} 
18630 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
18640 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
18650 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
18660 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 34  0..**.** {F13624
18670 7d 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  } If the value n
18680 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
18690 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
186a0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
186b0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
186c0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
186d0 20 20 7b 46 31 33 36 32 35 7d 20 54 68 65 20 72    {F13625} The r
186e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
186f0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 74  s.** always in t
18700 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
18710 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
18720 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
18730 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
18740 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
18750 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
18760 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
18770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18780 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
18790 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
187a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
187b0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
187c0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
187d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
187e0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
187f0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
18800 4e 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a  Name {F13640}.**
18810 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54 68 69  .** {F13641} Thi
18820 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
18830 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  s the index of a
18840 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
18850 77 69 74 68 20 74 68 65 0a 2a 2a 20 67 69 76 65  with the.** give
18860 6e 20 6e 61 6d 65 2e 20 20 7b 46 31 33 36 34 32  n name.  {F13642
18870 7d 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 20  } The name must 
18880 6d 61 74 63 68 20 65 78 61 63 74 6c 79 2e 20 20  match exactly.  
18890 7b 46 31 33 36 34 33 7d 0a 2a 2a 20 49 66 20 6e  {F13643}.** If n
188a0 6f 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  o parameter with
188b0 20 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20   the given name 
188c0 69 73 20 66 6f 75 6e 64 2c 20 72 65 74 75 72 6e  is found, return
188d0 20 30 2e 0a 2a 2a 20 7b 46 31 33 36 34 34 7d 20   0..** {F13644} 
188e0 50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 20  Parameter names 
188f0 6d 75 73 74 20 62 65 20 55 54 46 38 2e 0a 2a 2f  must be UTF8..*/
18900 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
18910 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
18920 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
18930 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
18940 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
18950 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
18960 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
18970 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
18980 20 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F13660}.**.** 
18990 7b 46 31 33 36 36 31 7d 20 43 6f 6e 74 72 61 72  {F13661} Contrar
189a0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
189b0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
189c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
189d0 65 73 20 6e 6f 74 0a 2a 2a 20 72 65 73 65 74 20  es not.** reset 
189e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
189f0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
18a00 73 5d 20 6f 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c  s] on a .** [sql
18a10 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
18a20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
18a30 20 7b 46 31 33 36 36 32 7d 20 55 73 65 20 74 68   {F13662} Use th
18a40 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a  is routine to.**
18a50 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
18a60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
18a70 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
18a80 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
18a90 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
18aa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18ab0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
18ac0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
18ad0 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a 2a   Set {F13710}.**
18ae0 0a 2a 2a 20 7b 46 31 33 37 31 31 7d 20 52 65 74  .** {F13711} Ret
18af0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
18b00 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
18b10 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
18b20 72 6e 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  rned by the .** 
18b30 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
18b40 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
18b50 74 65 6d 65 6e 74 5d 2e 20 7b 46 31 33 37 31 32  tement]. {F13712
18b60 7d 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  } This routine r
18b70 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69 66 20 70  eturns 0.** if p
18b80 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 20 73  Stmt is an SQL s
18b90 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
18ba0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
18bb0 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65 78 61 6d  ta (for .** exam
18bc0 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a  ple an UPDATE)..
18bd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
18be0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
18bf0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
18c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18c10 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
18c20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
18c30 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F13720}.**.** {
18c40 46 31 33 37 32 31 7d 20 54 68 65 73 65 20 72 6f  F13721} These ro
18c50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
18c60 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
18c70 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
18c80 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
18c90 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
18ca0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
18cb0 74 2e 20 20 7b 46 31 33 37 32 32 7d 20 54 68 65  t.  {F13722} The
18cc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
18cd0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
18ce0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
18cf0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
18d00 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 38 20  terminated UTF8 
18d10 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
18d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
18d30 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
18d40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
18d50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18d60 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 7b 46  UTF16 string. {F
18d70 31 33 37 32 33 7d 20 20 54 68 65 20 66 69 72 73  13723}  The firs
18d80 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
18d90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
18da0 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20 73  tmt | prepared s
18db0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
18dc0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 53 45  mplements the SE
18dd0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 0a  LECT statement..
18de0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18df0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 63  rameter is the c
18e00 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
18e10 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
18e20 75 6d 6e 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72  umn is.** number
18e30 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32   0..**.** {F1372
18e40 34 7d 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  4} The returned 
18e50 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
18e60 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
18e70 74 68 65 72 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ther the .** [sq
18e80 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65  lite3_stmt | pre
18e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
18ea0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
18eb0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
18ec0 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75 6e 74 69  ze()].** or unti
18ed0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
18ee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
18ef0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
18f00 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
18f10 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
18f20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  column..**.** {F
18f30 31 33 37 32 35 7d 20 49 66 20 73 71 6c 69 74 65  13725} If sqlite
18f40 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
18f50 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
18f60 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
18f70 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
18f80 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
18f90 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
18fa0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
18fb0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
18fc0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
18fd0 75 72 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  urned..*/.const 
18fe0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
18ff0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
19000 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
19010 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
19020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
19030 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
19040 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
19050 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
19060 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
19070 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33  uery Result {F13
19080 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  740}.**.** {F137
19090 34 31 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e  41} These routin
190a0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
190b0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
190c0 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
190d0 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
190e0 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
190f0 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c   result of a SEL
19100 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
19110 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 7b 46 31  mes from..** {F1
19120 33 37 34 32 7d 20 54 68 65 20 6e 61 6d 65 20 6f  3742} The name o
19130 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
19140 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
19150 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
19160 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
19170 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73   UTF8 or UTF16 s
19180 74 72 69 6e 67 2e 20 20 7b 46 31 33 37 34 33 7d  tring.  {F13743}
19190 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20   The _database_ 
191a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
191b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
191c0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
191d0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
191e0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
191f0 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
19200 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
19210 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
19220 6e 61 6d 65 2e 20 7b 46 31 33 37 34 34 7d 0a 2a  name. {F13744}.*
19230 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
19240 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
19250 6e 74 69 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ntil.** the [sql
19260 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70  ite3_stmt | prep
19270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
19280 69 73 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  is destroyed usi
19290 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
192a0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
192b0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
192c0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
192d0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
192e0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
192f0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46  coding..**.** {F
19300 31 33 37 34 35 7d 20 54 68 65 20 6e 61 6d 65 73  13745} The names
19310 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
19320 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
19330 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
19340 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
19350 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
19360 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 36  n..**.** {F13746
19370 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
19380 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c  ment to the foll
19390 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61  owing calls is a
193a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
193b0 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
193c0 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  L statement]..**
193d0 20 7b 46 31 33 37 34 37 7d 20 54 68 65 73 65 20   {F13747} These 
193e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
193f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
19400 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  ut the Nth colum
19410 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  n returned by .*
19420 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
19430 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
19440 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
19450 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
19460 7b 46 31 33 37 34 38 7d 20 49 66 20 74 68 65 20  {F13748} If the 
19470 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
19480 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
19490 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
194a0 73 73 69 6f 6e 0a 2a 2a 20 6f 72 20 73 75 62 71  ssion.** or subq
194b0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
194c0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
194d0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
194e0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  e functions.** r
194f0 65 74 75 72 6e 20 4e 55 4c 4c 2e 20 20 7b 46 31  eturn NULL.  {F1
19500 33 37 34 39 7d 20 4f 74 68 65 72 77 69 73 65 2c  3749} Otherwise,
19510 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
19520 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65   .** name of the
19530 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
19540 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  se, table and co
19550 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
19560 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
19570 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
19580 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  rom..**.** {F137
19590 35 30 7d 20 41 73 20 77 69 74 68 20 61 6c 6c 20  50} As with all 
195a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
195b0 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78  s, those postfix
195c0 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  ed with "16" ret
195d0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
195e0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74  coded strings, t
195f0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
19600 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
19610 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
19620 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
19630 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
19640 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
19650 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
19660 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
19670 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
19680 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
19690 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
196a0 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a  *.** {U13751}.**
196b0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
196c0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
196d0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
196e0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
196f0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
19700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19710 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
19720 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
19730 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
19740 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
19750 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
19760 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
19770 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
19780 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
19790 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
197a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
197b0 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
197c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
197d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
197e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
197f0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
19800 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
19810 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
19820 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
19830 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
19840 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
19850 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
19860 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
19870 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
19880 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
19890 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
198a0 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
198b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
198c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
198d0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
198e0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
198f0 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a  lt {F13760}.**.*
19900 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
19910 6d 65 74 65 72 20 69 73 20 61 20 5b 73 71 6c 69  meter is a [sqli
19920 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69  te3_stmt | compi
19930 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
19940 74 5d 2e 20 0a 2a 2a 20 7b 46 31 33 37 36 31 7d  t]. .** {F13761}
19950 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
19960 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73  nt is a SELECT s
19970 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
19980 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
19990 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  he .** returned 
199a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
199b0 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
199c0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
199d0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
199e0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
199f0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
19a00 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
19a10 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
19a20 72 65 74 75 72 6e 65 64 2e 20 20 7b 46 31 33 37  returned.  {F137
19a30 36 32 7d 20 49 66 20 74 68 65 20 4e 74 68 20 63  62} If the Nth c
19a40 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
19a50 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
19a60 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
19a70 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
19a80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
19a90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 7b 46 31  returned..** {F1
19aa0 33 37 36 33 7d 20 54 68 65 20 72 65 74 75 72 6e  3763} The return
19ab0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
19ac0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
19ad0 64 2e 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f  d.  {END} .** Fo
19ae0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68  r example, in th
19af0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
19b00 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
19b10 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
19b20 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20  ANT);.**.** And 
19b30 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
19b40 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64  atement compiled
19b50 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
19b60 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
19b70 31 3b 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68  1;.**.** Then th
19b80 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
19b90 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
19ba0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
19bb0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72   the second.** r
19bc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
19bd0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
19be0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
19bf0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
19c00 75 6d 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a  umn.** (i==0)..*
19c10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
19c20 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
19c30 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
19c40 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
19c50 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
19c60 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
19c70 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
19c80 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
19c90 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
19ca0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
19cb0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
19cc0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
19cd0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
19ce0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
19cf0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
19d00 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
19d10 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
19d20 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
19d30 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
19d40 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
19d50 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
19d60 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
19d70 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
19d80 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
19d90 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
19da0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2c 20 69 6e  lite3_stmt *, in
19db0 74 20 69 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t i);.const void
19dc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
19dd0 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
19de0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
19df0 0a 2f 2a 20 0a 2a 2a 20 43 41 50 49 33 52 45 46  ./* .** CAPI3REF
19e00 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  :  Evaluate An S
19e10 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31  QL Statement {F1
19e20 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65  3200}.**.** Afte
19e30 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  r an [sqlite3_st
19e40 6d 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65  mt | SQL stateme
19e50 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
19e60 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c  pared with a cal
19e70 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b  l.** to either [
19e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
19e90 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
19ea0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
19eb0 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a  ] or to one of.*
19ec0 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  * the legacy int
19ed0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
19ee0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
19ef0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
19f00 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  6()],.** then th
19f10 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  is function must
19f20 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
19f30 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
19f40 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a  evaluate the .**
19f50 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
19f60 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
19f70 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
19f80 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74   this sqlite3_st
19f90 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
19fa0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
19fb0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
19fc0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
19fd0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
19fe0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
19ff0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a000 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1a010 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1a020 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
1a030 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
1a040 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
1a050 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
1a060 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1a070 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
1a080 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
1a090 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
1a0a0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
1a0b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
1a0c0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
1a0d0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
1a0e0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
1a0f0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
1a100 49 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e  In the lagacy in
1a110 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
1a120 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
1a130 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
1a140 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  _BUSY], .** [SQL
1a150 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
1a160 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
1a170 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
1a180 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
1a190 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
1a1a0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
1a1b0 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54  the other [SQLIT
1a1c0 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
1a1d0 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  de].** or [SQLIT
1a1e0 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
1a1f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a200 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65  ode] might be re
1a210 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c  turned as.** wel
1a220 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
1a230 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
1a240 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
1a250 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
1a260 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
1a270 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
1a280 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
1a290 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
1a2a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1a2b0 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63   COMMIT.** or oc
1a2c0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
1a2d0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1a2e0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
1a2f0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
1a300 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
1a310 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
1a320 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20  is not a COMMIT 
1a330 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
1a340 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
1a350 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
1a360 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
1a370 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
1a380 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
1a390 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
1a3a0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
1a3b0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
1a3c0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
1a3d0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
1a3e0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
1a3f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1a400 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
1a410 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
1a420 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
1a430 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
1a440 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
1a450 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
1a460 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
1a470 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
1a480 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
1a490 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
1a4a0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1a4b0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
1a4c0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
1a4d0 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53  ata, then .** [S
1a4e0 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65  QLITE_ROW] is re
1a4f0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
1a500 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
1a510 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66  ta is ready.** f
1a520 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
1a530 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65   the caller. The
1a540 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
1a550 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a  ccessed using.**
1a560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1a570 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d  lumn_int | colum
1a580 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
1a590 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
1a5a0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
1a5b0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
1a5c0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
1a5d0 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20  of data..** .** 
1a5e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
1a5f0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
1a600 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
1a610 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
1a620 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
1a630 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
1a640 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
1a650 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
1a660 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
1a670 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
1a680 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
1a690 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
1a6a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1a6b0 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c  ]..** With the l
1a6c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
1a6d0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
1a6e0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
1a6f0 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple:.** [SQLITE
1a700 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
1a710 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
1a720 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
1a730 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
1a740 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
1a750 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1a760 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
1a770 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a780 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
1a790 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e   statement].  In
1a7a0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1a7b0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
1a7c0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
1a7d0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
1a7e0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
1a7f0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
1a800 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
1a810 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
1a820 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
1a830 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
1a840 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
1a850 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
1a860 6c 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65  led on a [sqlite
1a870 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
1a880 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1a890 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
1a8a0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
1a8b0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
1a8c0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
1a8d0 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76  hat had .** prev
1a8e0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
1a8f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
1a900 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
1a910 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
1a920 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
1a930 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
1a940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1a950 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
1a960 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
1a970 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
1a980 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
1a990 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  e..**.** <b>Goof
1a9a0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
1a9b0 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65  t:</b>.** In the
1a9c0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1a9d0 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  e, .** the sqlit
1a9e0 65 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c  e3_step() API al
1a9f0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
1aa00 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
1aa10 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  e,.** [SQLITE_ER
1aa20 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
1aa30 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20  any error other 
1aa40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
1aa50 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54  Y].** and [SQLIT
1aa60 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
1aa70 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74  must call [sqlit
1aa80 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
1aa90 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
1aaa0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
1aab0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
1aac0 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b  he specific.** [
1aad0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
1aae0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61  esult codes] tha
1aaf0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
1ab00 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
1ab10 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
1ab20 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
1ab30 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
1ab40 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
1ab50 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
1ab60 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
1ab70 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
1ab80 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
1ab90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
1aba0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1abb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1abc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1abd0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
1abe0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
1abf0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
1ac00 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
1ac10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ac20 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a  ()], then the .*
1ac30 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  * more specific 
1ac40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
1ac50 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
1ac60 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
1ac70 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
1ac80 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
1ac90 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
1aca0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
1acb0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
1acc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
1acd0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
1ace0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1acf0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1ad00 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20  in a result set 
1ad10 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52  {F13770}.**.** R
1ad20 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
1ad30 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
1ad40 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
1ad50 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
1ad60 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20  .**.** {F13771} 
1ad70 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20  After a call to 
1ad80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1ad90 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53   that returns [S
1ada0 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 74  QLITE_ROW],.** t
1adb0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 77  his routine.** w
1adc0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
1add0 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65  ame value as the
1ade0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1adf0 5f 63 6f 75 6e 74 28 29 5d 20 66 75 6e 63 74 69  _count()] functi
1ae00 6f 6e 2e 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 0a  on..** {F13772}.
1ae10 2a 2a 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65  ** After [sqlite
1ae20 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
1ae30 74 75 72 6e 65 64 20 61 6e 20 5b 53 51 4c 49 54  turned an [SQLIT
1ae40 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
1ae50 5f 42 55 53 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20  _BUSY], or.** a 
1ae60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
1ae70 65 72 72 6f 72 20 63 6f 64 65 5d 2c 20 6f 72 20  error code], or 
1ae80 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
1ae90 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
1aea0 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 20 74   .** called on t
1aeb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1aec0 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
1aed0 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66  ement] for the f
1aee0 69 72 73 74 20 74 69 6d 65 2c 0a 2a 2a 20 74 68  irst time,.** th
1aef0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
1af00 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20  ns zero..*/.int 
1af10 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
1af20 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
1af30 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1af40 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
1af50 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20  ental Datatypes 
1af60 7b 46 31 30 32 36 35 7d 0a 2a 2a 0a 2a 2a 20 7b  {F10265}.**.** {
1af70 46 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 6c  F10266}Every val
1af80 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
1af90 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
1afa0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
1afb0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
1afc0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
1afd0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
1afe0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
1aff0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1b000 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
1b010 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
1b020 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
1b030 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
1b040 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
1b050 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
1b060 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
1b070 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
1b080 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
1b090 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
1b0a0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
1b0b0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1b0c0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
1b0d0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
1b0e0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
1b0f0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
1b100 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
1b110 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
1b120 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
1b130 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
1b140 53 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74  SQLITE3_TEXT not
1b150 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
1b160 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1b170 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
1b180 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
1b190 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
1b1a0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
1b1b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1b1c0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
1b1d0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
1b1e0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
1b1f0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
1b200 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
1b210 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
1b220 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
1b230 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
1b240 49 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56  I3REF: Results V
1b250 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
1b260 72 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a  ry {F13800}.**.*
1b270 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b280 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1b290 69 6f 6e 20 61 62 6f 75 74 0a 2a 2a 20 61 20 73  ion about.** a s
1b2a0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
1b2b0 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
1b2c0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
1b2d0 79 2e 20 20 49 6e 20 65 76 65 72 79 0a 2a 2a 20  y.  In every.** 
1b2e0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
1b2f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
1b300 6e 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  nter to the .** 
1b310 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
1b320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  SQL statement] t
1b330 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a 20  hat is being.** 
1b340 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
1b350 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 74  sqlite3_stmt*] t
1b360 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
1b370 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
1b380 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b390 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
1b3a0 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a 20  ariants) and.** 
1b3b0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
1b3c0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
1b3d0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
1b3e0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
1b3f0 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  tion .** should 
1b400 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  be returned.  Th
1b410 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
1b420 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
1b430 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20 69   set.** has an i
1b440 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a  ndex of 0..**.**
1b450 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
1b460 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75 72  ement is not cur
1b470 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
1b480 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
1b490 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63 6f  if the.** the co
1b4a0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
1b4b0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
1b4c0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
1b4d0 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20 72  ned. .** These r
1b4e0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
1b4f0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
1b500 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1b510 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
1b520 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
1b530 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
1b540 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
1b550 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
1b560 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
1b570 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1b580 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73 75  has been call su
1b590 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
1b5a0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
1b5b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1b5c0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
1b5d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
1b5e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1b5f0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
1b600 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b610 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
1b620 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
1b630 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
1b640 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
1b650 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
1b660 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
1b670 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
1b680 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
1b690 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1b6a0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
1b6b0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
1b6c0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
1b6d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
1b6e0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
1b6f0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
1b700 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
1b710 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ed.  .**.** The 
1b720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1b730 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
1b740 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
1b750 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
1b760 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
1b770 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
1b780 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
1b790 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
1b7a0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
1b7b0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
1b7c0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
1b7d0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
1b7e0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
1b7f0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
1b800 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
1b810 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
1b820 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1b830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
1b840 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
1b850 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
1b860 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
1b870 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
1b880 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
1b890 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
1b8a0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
1b8b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b8c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
1b8d0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
1b8e0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
1b8f0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
1b900 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
1b910 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
1b920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1b930 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
1b940 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
1b950 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
1b960 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
1b970 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
1b980 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
1b990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
1b9a0 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  s() .** routine 
1b9b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1b9c0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1b9d0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
1b9e0 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
1b9f0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
1ba00 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
1ba10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
1ba20 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
1ba30 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
1ba40 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
1ba50 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1ba60 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
1ba70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
1ba80 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
1ba90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
1baa0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
1bab0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
1bac0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
1bad0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
1bae0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
1baf0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
1bb00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1bb10 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
1bb20 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
1bb30 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
1bb40 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
1bb50 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
1bb60 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
1bb70 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
1bb80 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
1bb90 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
1bba0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1bbb0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
1bbc0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
1bbd0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1bbe0 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73  s..**.** Strings
1bbf0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1bc00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1bc10 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
1bc20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
1bc30 2a 2a 20 65 76 65 6e 20 7a 65 72 6f 2d 6c 65 6e  ** even zero-len
1bc40 67 74 68 20 73 74 72 69 6e 67 73 2c 20 61 72 65  gth strings, are
1bc50 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
1bc60 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
1bc70 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
1bc80 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
1bc90 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
1bca0 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f 62 20  ero-length blob 
1bcb0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
1bcc0 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
1bcd0 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
1bce0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1bcf0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
1bd00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
1bd10 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1bd20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
1bd30 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
1bd40 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
1bd50 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 73  lt in UTF-16 ins
1bd60 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20  tead of UTF-8.  
1bd70 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
1bd80 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
1bd90 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
1bda0 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
1bdb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
1bdc0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
1bdd0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
1bde0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
1bdf0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
1be00 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
1be10 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
1be20 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
1be30 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
1be40 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
1be50 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
1be60 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
1be70 74 6f 20 64 6f 20 74 68 65 20 63 6f 6e 76 65 72  to do the conver
1be80 73 69 6f 6e 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  sion.** automati
1be90 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
1bea0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
1beb0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
1bec0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ons that.** are 
1bed0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
1bee0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
1bef0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
1bf00 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
1bf10 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
1bf20 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
1bf30 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
1bf40 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
1bf50 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
1bf60 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
1bf70 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
1bf80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
1bf90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
1bfa0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
1bfb0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
1bfc0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
1bfd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
1bfe0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
1bff0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
1c000 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
1c010 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
1c020 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
1c030 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
1c040 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
1c050 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
1c060 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
1c070 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
1c080 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
1c090 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
1c0a0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
1c0b0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
1c0c0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
1c0d0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
1c0e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
1c0f0 6d 65 20 61 73 20 66 6f 72 20 49 4e 54 45 47 45  me as for INTEGE
1c100 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
1c110 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
1c120 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
1c130 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
1c140 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
1c150 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
1c160 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
1c170 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
1c180 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
1c190 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
1c1a0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
1c1b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
1c1c0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
1c1d0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
1c1e0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
1c1f0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
1c200 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
1c210 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
1c220 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
1c230 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
1c240 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
1c250 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
1c260 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
1c270 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
1c280 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
1c290 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
1c2a0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
1c2b0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
1c2c0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
1c2d0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
1c2e0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
1c2f0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
1c300 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
1c310 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
1c320 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
1c330 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
1c340 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
1c350 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
1c360 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
1c370 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
1c380 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
1c390 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1c3a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
1c3b0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
1c3c0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
1c3d0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
1c3e0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
1c3f0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 6e 20  t has its.** on 
1c400 65 71 75 61 76 61 6c 65 6e 74 20 69 6e 74 65 72  equavalent inter
1c410 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
1c420 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
1c430 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
1c440 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
1c450 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
1c460 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
1c470 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
1c480 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
1c490 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
1c4a0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
1c4b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
1c4c0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
1c4d0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
1c4e0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
1c4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
1c500 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
1c510 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
1c520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
1c530 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
1c540 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20  be invalidated. 
1c550 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
1c560 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
1c570 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
1c580 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
1c590 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
1c5a0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
1c5b0 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20 54 68 65  .** <li><p>  The
1c5c0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
1c5d0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
1c5e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
1c5f0 78 74 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  xt() .**        
1c600 20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c    or sqlite3_col
1c610 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
1c620 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
1c630 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
1c640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 65  .**          nee
1c650 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
1c660 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 70 3e   the string.</p>
1c670 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1c680 3c 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c  <p>  The initial
1c690 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
1c6a0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
1c6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
1c6c0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  6() or.**       
1c6d0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
1c6e0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
1c6f0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
1c700 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
1c710 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rted.**         
1c720 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c   to UTF-16.</p><
1c730 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c  /li>.**.** <li><
1c740 70 3e 20 20 54 68 65 20 69 6e 69 74 69 61 6c 20  p>  The initial 
1c750 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
1c760 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
1c770 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
1c780 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ) or.**         
1c790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
1c7a0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
1c7b0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
1c7c0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1c7e0 55 54 46 2d 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  UTF-8.</p></li>.
1c7f0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
1c800 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
1c810 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
1c820 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
1c830 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
1c840 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
1c850 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
1c860 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
1c870 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
1c880 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
1c890 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
1c8a0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
1c8b0 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
1c8c0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
1c8d0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
1c8e0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
1c8f0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
1c900 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
1c910 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
1c920 65 74 69 6d 65 20 69 74 20 69 73 0a 2a 2a 20 6e  etime it is.** n
1c930 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
1c940 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
1c950 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
1c960 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 20 20  e invalidated.  
1c970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
1c980 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
1c990 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
1c9a0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
1c9b0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
1c9c0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
1c9d0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
1c9e0 0a 2a 2a 20 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  .**  <ul>.**  <l
1c9f0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
1ca00 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
1ca10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
1ca20 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
1ca30 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
1ca40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
1ca50 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
1ca60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
1ca70 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
1ca80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1ca90 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
1caa0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
1cab0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
1cac0 2a 2a 20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  **  </ul>.**.** 
1cad0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
1cae0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
1caf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1cb00 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  ext(), sqlite3_c
1cb10 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  olumn_blob(),.**
1cb20 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
1cb30 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
1cb40 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
1cb50 65 73 75 6c 74 20 69 6e 74 6f 20 74 68 65 20 64  esult into the d
1cb60 65 73 69 72 65 64 0a 2a 2a 20 66 6f 72 6d 61 74  esired.** format
1cb70 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
1cb80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
1cb90 65 73 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  es() or sqlite3_
1cba0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
1cbb0 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 74 68 65 20   to.** find the 
1cbc0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
1cbd0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
1cbe0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1cbf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
1cc00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
1cc10 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
1cc20 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
1cc30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
1cc40 2e 20 20 41 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a  .  And do not.**
1cc50 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
1cc60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1cc70 74 31 36 28 29 20 77 69 74 68 20 63 61 6c 6c 73  t16() with calls
1cc80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
1cc90 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
1cca0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
1ccb0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
1ccc0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
1ccd0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
1cce0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
1ccf0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
1cd00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cd10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cd20 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
1cd30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1cd40 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
1cd50 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
1cd60 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
1cd70 6e 67 73 0a 2a 2a 20 61 6e 64 20 62 6c 6f 62 73  ngs.** and blobs
1cd80 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
1cd90 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
1cda0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
1cdb0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
1cdc0 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
1cdd0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
1cde0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1cdf0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
1ce00 6f 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  o .** [sqlite3_f
1ce10 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
1ce20 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1ce30 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
1ce40 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
1ce50 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
1ce60 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
1ce70 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
1ce80 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
1ce90 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
1cea0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
1ceb0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
1cec0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
1ced0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
1cee0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
1cef0 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
1cf00 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1cf10 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
1cf20 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
1cf30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f  QLITE_NOMEM]..*/
1cf40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1cf50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
1cf60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1cf70 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
1cf80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
1cf90 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
1cfa0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
1cfb0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
1cfc0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
1cfd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
1cfe0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
1cff0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
1d000 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1d010 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
1d020 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
1d030 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1d040 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
1d050 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d060 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
1d070 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1d080 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
1d090 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
1d0a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1d0b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1d0c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
1d0d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1d0e0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
1d0f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1d100 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
1d110 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
1d120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d130 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
1d140 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
1d150 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
1d160 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1d170 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
1d180 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
1d190 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
1d1a0 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33  ment Object {F13
1d1b0 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  300}.**.** The s
1d1c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1d1d0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
1d1e0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
1d1f0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
1d200 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51  mt | compiled SQ
1d210 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 49 66  L statement]. If
1d220 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
1d230 61 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 73  as.** executed s
1d240 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 6f 72 20  uccessfully, or 
1d250 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
1d260 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  all, then SQLITE
1d270 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
1d280 0a 2a 2a 20 49 66 20 65 78 65 63 75 74 69 6f 6e  .** If execution
1d290 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
1d2a0 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
1d2b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
1d2c0 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
1d2d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1d2e0 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
1d2f0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  d error code].**
1d300 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a   is returned. .*
1d310 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1d320 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
1d330 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
1d340 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1d350 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  n of the.** [sql
1d360 69 74 65 33 5f 73 74 6d 74 20 7c 20 76 69 72 74  ite3_stmt | virt
1d370 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e 20 20 49  ual machine].  I
1d380 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
1d390 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 20 0a 2a  chine has not .*
1d3a0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
1d3b0 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
1d3c0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
1d3d0 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
1d3e0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
1d3f0 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 69  an error or an i
1d400 6e 74 65 72 72 75 70 74 2e 20 20 28 53 65 65 20  nterrupt.  (See 
1d410 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1d420 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49 6e 63 6f  pt()].) .** Inco
1d430 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
1d440 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
1d450 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
1d460 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c 20 20 0a  ns cancelled,  .
1d470 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
1d480 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
1d490 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a 2a 20 5b  s, and the .** [
1d4a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
1d4b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 72 65 74 75  esult code] retu
1d4c0 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
1d4d0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a  LITE_ABORT]..*/.
1d4e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
1d4f0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
1d500 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1d510 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
1d520 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
1d530 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46  tement Object {F
1d540 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13330}.**.** The
1d550 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
1d560 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
1d570 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a  led to reset a .
1d580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
1d590 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20   | compiled SQL 
1d5a0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
1d5b0 74 2e 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 69 74  t..** back to it
1d5c0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
1d5d0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
1d5e0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
1d5f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
1d600 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
1d610 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
1d620 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
1d630 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
1d640 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
1d650 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
1d660 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
1d670 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
1d680 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
1d690 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
1d6a0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2f 0a  he bindings..*/.
1d6b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
1d6c0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
1d6d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1d6e0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
1d6f0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
1d700 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31 30  Functions {F1610
1d710 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  0}.**.** The fol
1d720 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
1d730 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
1d740 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
1d750 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
1d760 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65 66 69  .** or to redefi
1d770 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ne the behavior 
1d780 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
1d790 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
1d7a0 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a 2a 2a  regates.  The.**
1d7b0 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 6c 79   difference only
1d7c0 20 62 65 74 77 65 65 6e 20 74 68 65 20 74 77 6f   between the two
1d7d0 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
1d7e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
1d7f0 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  he.** name of th
1d800 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
1d810 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
1d820 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
1d830 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1d840 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1d850 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
1d860 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  6 for sqlite3_cr
1d870 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
1d880 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
1d890 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
1d8a0 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20 64 61  he [sqlite3 | da
1d8b0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d 20 74  tabase handle] t
1d8c0 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a 2a 2a  hat holds the.**
1d8d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
1d8e0 20 61 67 67 72 65 67 61 74 65 20 69 73 20 74 6f   aggregate is to
1d8f0 20 62 65 20 61 64 64 65 64 20 6f 72 20 72 65 64   be added or red
1d900 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73 69 6e  efined. If a sin
1d910 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  gle.** program u
1d920 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
1d930 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
1d940 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  e internally, th
1d950 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  en SQL.** functi
1d960 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
1d970 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
1d980 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 20  individually to 
1d990 65 61 63 68 20 64 61 74 61 62 61 73 65 0a 2a 2a  each database.**
1d9a0 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77 68 69   handle with whi
1d9b0 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62 65 20  ch they will be 
1d9c0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  used..**.** The 
1d9d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d9e0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1d9f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1da00 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 0a 2a   to be created.*
1da10 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64 2e 0a  * or redefined..
1da20 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** The length of
1da30 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
1da40 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
1da50 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  s, exclusive of 
1da60 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74 65 72  the .** zero-ter
1da70 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
1da80 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
1da90 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
1daa0 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
1dab0 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61  aracters.  Any a
1dac0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
1dad0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
1dae0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
1daf0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
1db00 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   an SQLITE_ERROR
1db10 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
1db20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1db30 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  r is the number 
1db40 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
1db50 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
1db60 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
1db70 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69  te takes. If thi
1db80 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
1db90 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
1dba0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
1dbb0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
1dbc0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
1dbd0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
1dbe0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
1dbf0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
1dc00 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
1dc10 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c 49 54   what .** [SQLIT
1dc20 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
1dc30 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
1dc40 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
1dc50 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
1dc60 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
1dc70 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
1dc80 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
1dc90 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
1dca0 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
1dcb0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
1dcc0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
1dcd0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
1dce0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
1dcf0 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
1dd00 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
1dd10 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
1dd20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  It is allowed to
1dd30 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
1dd40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1dd50 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
1dd60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
1dd70 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
1dd80 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
1dd90 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
1dda0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
1ddb0 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
1ddc0 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74  ep..** When mult
1ddd0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
1dde0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
1ddf0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
1de00 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
1de10 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
1de20 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
1de30 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
1de40 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
1de50 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
1de60 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
1de70 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
1de80 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
1de90 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a 2a 20  ot care what.** 
1dea0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
1deb0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
1dec0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
1ded0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b 53 51  should be.** [SQ
1dee0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
1def0 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   The fifth param
1df00 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
1df10 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
1df20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1df30 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75 6e 63  n.** of the func
1df40 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
1df50 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
1df60 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  nter using.** [s
1df70 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1df80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
1df90 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
1dfa0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
1dfb0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
1dfc0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
1dfd0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
1dfe0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
1dff0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
1e000 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a 2a 20  ment the SQL.** 
1e010 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
1e020 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
1e030 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
1e040 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
1e050 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ntation of.** th
1e060 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61 63 6b  e xFunc callback
1e070 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
1e080 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
1e090 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
1e0a0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
1e0b0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
1e0c0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
1e0d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
1e0e0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
1e0f0 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20 61 6e  n.** of xStep an
1e100 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
1e110 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
1e120 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
1e130 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20 65 78   delete an.** ex
1e140 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
1e150 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
1e160 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
1e170 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
1e180 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 2e 0a  on.** callback..
1e190 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d  **.** It is perm
1e1a0 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
1e1b0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
1e1c0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
1e1d0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
1e1e0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
1e1f0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
1e200 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
1e210 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
1e220 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
1e230 65 72 69 6e 67 20 70 65 72 66 65 72 72 65 64 20  ering perferred 
1e240 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
1e250 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
1e260 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
1e270 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73  tation most clos
1e280 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
1e290 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
1e2a0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
1e2b0 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69 6e 74   is used..*/.int
1e2c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1e2d0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
1e2e0 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  te3 *,.  const c
1e2f0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
1e300 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
1e310 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
1e320 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 20    void*,.  void 
1e330 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
1e340 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
1e350 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
1e360 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
1e370 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
1e380 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
1e390 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
1e3a0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
1e3b0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
1e3c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1e3d0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
1e3e0 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
1e3f0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
1e400 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
1e410 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
1e420 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
1e430 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
1e440 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
1e450 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
1e460 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
1e470 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
1e480 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
1e490 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
1e4a0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
1e4b0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
1e4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e4d0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46  ext Encodings {F
1e4e0 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10267}.**.** The
1e4f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
1e500 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
1e510 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
1e520 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
1e530 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
1e540 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
1e550 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1e560 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
1e570 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1e580 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
1e590 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
1e5a0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
1e5b0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1e5c0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
1e5d0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
1e5e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1e5f0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1e600 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
1e610 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
1e620 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1e630 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
1e640 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
1e650 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
1e660 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1e670 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
1e680 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1e690 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63  F: Obsolete Func
1e6a0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1e6b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
1e6c0 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65  all now obsolete
1e6d0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
1e6e0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
1e6f0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1e700 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
1e710 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20  de, we continue 
1e720 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68  to support.** th
1e730 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
1e740 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76  However, new dev
1e750 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74  elopment project
1e760 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
1e770 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
1e780 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
1e790 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
1e7a0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
1e7b0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
1e7c0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
1e7d0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
1e7e0 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65  ell you want the
1e7f0 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  y do..*/.int sql
1e800 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1e810 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
1e820 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  text*);.int sqli
1e830 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
1e840 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20  te3_stmt*);.int 
1e850 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
1e860 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
1e870 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
1e880 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
1e890 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
1e8a0 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20  ver(void);.void 
1e8b0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
1e8c0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e  leanup(void);.in
1e8d0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
1e8e0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
1e8f0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
1e900 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
1e910 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f  lite3_int64);../
1e920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1e930 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
1e940 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
1e950 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a  Values {F15100}.
1e960 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
1e970 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
1e980 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
1e990 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
1e9a0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
1e9b0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
1e9c0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
1e9d0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
1e9e0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
1e9f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
1ea00 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
1ea10 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
1ea20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
1ea30 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
1ea40 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
1ea50 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
1ea60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1ea70 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
1ea80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1ea90 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
1eaa0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
1eab0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
1eac0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
1ead0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
1eae0 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
1eaf0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
1eb00 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
1eb10 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1eb20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
1eb30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
1eb40 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
1eb50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
1eb60 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
1eb70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1eb80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
1eb90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1eba0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
1ebb0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
1ebc0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1ebd0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
1ebe0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ebf0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
1ec00 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
1ec10 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
1ec20 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
1ec30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
1ec40 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
1ec50 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
1ec60 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
1ec70 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
1ec80 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
1ec90 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1eca0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
1ecb0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
1ecc0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
1ecd0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
1ece0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
1ecf0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
1ed00 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
1ed10 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
1ed20 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1ed30 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
1ed40 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
1ed50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ed60 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
1ed70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1ed80 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
1ed90 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
1eda0 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
1edb0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
1edc0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
1edd0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
1ede0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
1edf0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
1ee00 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
1ee10 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
1ee20 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
1ee30 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
1ee40 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
1ee50 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
1ee60 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
1ee70 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
1ee80 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
1ee90 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
1eea0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
1eeb0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
1eec0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
1eed0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
1eee0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
1eef0 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
1ef00 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
1ef10 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
1ef20 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
1ef30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 64   conversion is d
1ef40 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20  one.  Otherwise 
1ef50 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
1ef60 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  curs.  The .** [
1ef70 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
1ef80 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
1ef90 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
1efa0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
1efb0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
1efc0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
1efd0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
1efe0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
1eff0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1f000 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
1f010 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
1f020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
1f030 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
1f040 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
1f050 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
1f060 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
1f070 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
1f080 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
1f090 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
1f0a0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
1f0b0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
1f0c0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
1f0d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
1f0e0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a  ue_text16()].  .
1f0f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1f100 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
1f110 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
1f120 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
1f130 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1f140 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
1f150 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e sqlite3_value*
1f160 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20   parameters..** 
1f170 4f 72 2c 20 69 66 20 74 68 65 20 73 71 6c 69 74  Or, if the sqlit
1f180 65 33 5f 76 61 6c 75 65 2a 20 61 72 67 75 6d 65  e3_value* argume
1f190 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68  nt comes from th
1f1a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
1f1b0 6e 5f 76 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e  n_value()].** in
1f1c0 74 65 72 66 61 63 65 2c 20 74 68 65 6e 20 74 68  terface, then th
1f1d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
1f1e0 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 66 72  uld be called fr
1f1f0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
1f200 61 64 0a 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b  ad.** that ran [
1f210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1f220 61 6c 75 65 28 29 5d 2e 0a 2a 2a 0a 2a 2f 0a 63  alue()]..**.*/.c
1f230 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1f240 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
1f250 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1f260 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
1f270 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
1f280 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
1f290 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
1f2a0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
1f2b0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
1f2c0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
1f2d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
1f2e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
1f2f0 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
1f300 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
1f310 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
1f320 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
1f330 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
1f340 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
1f350 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1f360 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
1f370 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1f380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
1f390 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
1f3a0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
1f3b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
1f3c0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
1f3d0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
1f3e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
1f3f0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
1f400 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1f410 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1f420 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
1f430 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1f440 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
1f450 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
1f460 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
1f470 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
1f480 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
1f490 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30 7d  Context {F16210}
1f4a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  .**.** The imple
1f4b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67  mentation of agg
1f4c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
1f4d0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f  ions use this ro
1f4e0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
1f4f0 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65  e.** a structure
1f500 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
1f510 69 72 20 73 74 61 74 65 2e 20 20 0a 2a 2a 20 7b  ir state.  .** {
1f520 46 31 36 32 31 31 7d 20 54 68 65 20 66 69 72 73  F16211} The firs
1f530 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
1f540 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1f550 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69  text() routine i
1f560 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66  s.** is called f
1f570 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
1f580 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74  aggregate, SQLit
1f590 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74  e allocates nByt
1f5a0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
1f5b0 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72  zeros that memor
1f5c0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
1f5d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a   pointer to it..
1f5e0 2a 2a 20 7b 46 31 36 32 31 32 7d 20 4f 6e 20 73  ** {F16212} On s
1f5f0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
1f600 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 73 71  uent calls to sq
1f610 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
1f620 63 6f 6e 74 65 78 74 28 29 0a 2a 2a 20 66 6f 72  context().** for
1f630 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
1f640 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
1f650 65 78 2c 20 74 68 65 20 73 61 6d 65 20 62 75 66  ex, the same buf
1f660 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
1f670 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 65 20 69 6d   {END}.** The im
1f680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1f690 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
1f6a0 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65 74   can use the ret
1f6b0 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
1f6c0 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
1f6d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 33 7d 20  .**.** {F16213} 
1f6e0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
1f6f0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61  ally frees the a
1f700 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20  llocated buffer 
1f710 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
1f720 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63  te.** query conc
1f730 6c 75 64 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ludes. {END}.**.
1f740 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
1f750 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
1f760 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 0a   a copy of the .
1f770 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1f780 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
1f790 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
1f7a0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1f7b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f7c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
1f7d0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
1f7e0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
1f7f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
1f800 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1f810 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1f820 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
1f830 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
1f840 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
1f850 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
1f860 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
1f870 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
1f880 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
1f890 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
1f8a0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
1f8b0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
1f8c0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
1f8d0 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a  ns {F16240}.**.*
1f8e0 2a 20 7b 46 31 36 32 34 31 7d 20 54 68 65 20 73  * {F16241} The s
1f8f0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1f900 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1f910 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
1f920 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
1f930 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
1f940 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
1f950 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
1f960 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 65  r).** of the the
1f970 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
1f980 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
1f990 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
1f9a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
1f9b0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
1f9c0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
1f9d0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
1f9e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
1f9f0 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
1fa00 0a 2a 2a 0a 2a 2a 20 7b 55 31 36 32 34 33 7d 20  .**.** {U16243} 
1fa10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
1fa20 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
1fa30 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
1fa40 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
1fa50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1fa60 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
1fa70 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
1fa80 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
1fa90 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
1faa0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
1fab0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
1fac0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
1fad0 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F16270}.**.** 
1fae0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
1faf0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
1fb00 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
1fb10 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
1fb20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
1fb30 6d 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61  meta-data with a
1fb40 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
1fb50 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
1fb60 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
1fb70 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
1fb80 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
1fb90 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
1fba0 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
1fbb0 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
1fbc0 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
1fbd0 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
1fbe0 65 64 20 6d 65 74 61 2d 64 61 74 61 20 6d 61 79  ed meta-data may
1fbf0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
1fc00 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
1fc10 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
1fc20 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
1fc30 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
1fc40 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
1fc50 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
1fc60 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
1fc70 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
1fc80 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
1fc90 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 2d 64 61  ed as.** meta-da
1fca0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
1fcb0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
1fcc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
1fcd0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
1fce0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
1fcf0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
1fd00 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
1fd10 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
1fd20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
1fd30 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
1fd40 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
1fd50 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
1fd60 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
1fd70 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
1fd80 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
1fd90 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
1fda0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ation..**.** {F1
1fdb0 36 32 37 31 7d 0a 2a 2a 20 54 68 65 20 73 71 6c  6271}.** The sql
1fdc0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1fdd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1fde0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1fdf0 6f 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a  o the meta-data.
1fe00 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
1fe10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
1fe20 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
1fe30 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
1fe40 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
1fe50 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
1fe60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
1fe70 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 46 31 36 32  nction..** {F162
1fe80 37 32 7d 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  72} If no meta-d
1fe90 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
1fea0 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  r been set for t
1feb0 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65  he Nth.** argume
1fec0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
1fed0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
1fee0 6f 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  oresponding func
1fef0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
1ff00 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  * has changed si
1ff10 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
1ff20 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20  a was set, then 
1ff30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1ff40 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ata().** returns
1ff50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1ff60 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 35 7d 20  .**.** {F16275} 
1ff70 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
1ff80 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
1ff90 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
1ffa0 74 61 2d 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  ta-data.** point
1ffb0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
1ffc0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
1ffd0 65 20 6d 65 74 61 2d 64 61 74 61 20 66 6f 72 20  e meta-data for 
1ffe0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
1fff0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
20000 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20010 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  function. {END} 
20020 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
20030 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
20040 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67  et_auxdata() mig
20050 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64  ht return this d
20060 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a  ata, if it has.*
20070 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72  * not been destr
20080 6f 79 65 64 2e 20 0a 2a 2a 20 7b 46 31 36 32 37  oyed. .** {F1627
20090 37 7d 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  7} If it is not 
200a0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
200b0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
200c0 74 72 75 63 74 6f 72 20 0a 2a 2a 20 66 75 6e 63  tructor .** func
200d0 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
200e0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
200f0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
20100 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
20110 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 68 65  he meta-data whe
20120 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
20130 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
20140 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
20150 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
20160 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
20170 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
20180 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 7b 45   comes first. {E
20190 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ND}.**.** In pra
201a0 63 74 69 63 65 2c 20 6d 65 74 61 2d 64 61 74 61  ctice, meta-data
201b0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
201c0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
201d0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
201e0 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
201f0 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
20200 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
20210 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
20220 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
20230 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
20240 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
20250 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
20260 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
20270 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
20280 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
20290 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
202a0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
202b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
202c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
202d0 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
202e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
202f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
20300 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
20310 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
20320 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
20330 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
20340 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
20350 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
20360 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a  or {F10280}.**.*
20370 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
20380 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ial value for th
20390 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
203a0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
203b0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
203c0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
203d0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
203e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
203f0 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
20400 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
20410 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
20420 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
20430 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
20440 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
20450 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
20460 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
20470 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
20480 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
20490 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  he .** SQLITE_TR
204a0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
204b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
204c0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
204d0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
204e0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
204f0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
20500 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
20510 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
20520 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
20530 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
20540 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
20550 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
20560 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
20570 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
20580 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
20590 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
205a0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
205b0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
205c0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
205d0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
205e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
205f0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
20600 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
20610 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
20620 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
20630 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
20640 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
20650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
20660 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
20670 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
20680 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a  tion {F16400}.**
20690 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
206a0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
206b0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
206c0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
206d0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
206e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
206f0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
20700 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
20710 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
20720 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
20730 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
20740 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
20750 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
20760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
20770 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
20780 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
20790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
207a0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
207b0 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20  _bind_*] family 
207c0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  of functions use
207d0 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c  d.** to bind val
207e0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
207f0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
20800 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
20810 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a  * Refer to the.*
20820 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
20830 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
20840 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74  ind_* documentat
20850 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69  ion] for.** addi
20860 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
20870 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30  on..**.** {F1640
20880 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  2} The sqlite3_r
20890 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
208a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
208b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
208c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
208d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
208e0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
208f0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
20900 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
20910 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
20920 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
20930 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
20940 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
20950 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
20960 2e 20 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54  . .** {F16403} T
20970 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
20980 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 65  t_zeroblob() ine
20990 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
209a0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
209b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
209c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
209d0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
209e0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
209f0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
20a00 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
20a10 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
20a20 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
20a30 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
20a40 36 34 30 37 7d 20 54 68 65 20 73 71 6c 69 74 65  6407} The sqlite
20a50 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
20a60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
20a70 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
20a80 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
20a90 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
20aa0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
20ab0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
20ac0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
20ad0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
20ae0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39  t..**.** {F16409
20af0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  } The sqlite3_re
20b00 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
20b10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
20b20 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
20b30 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
20b40 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
20b50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
20b60 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
20b70 0a 2a 2a 20 7b 46 31 36 34 31 31 7d 20 53 51 4c  .** {F16411} SQL
20b80 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
20b90 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
20ba0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
20bb0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
20bc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
20bd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
20be0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
20bf0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
20c00 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
20c10 20 7b 46 31 36 34 31 32 7d 20 53 51 4c 69 74 65   {F16412} SQLite
20c20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
20c30 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
20c40 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
20c50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
20c60 72 28 29 20 61 73 20 55 54 46 38 2e 20 20 7b 46  r() as UTF8.  {F
20c70 31 36 34 31 33 7d 20 53 51 4c 69 74 65 0a 2a 2a  16413} SQLite.**
20c80 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
20c90 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
20ca0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
20cb0 31 36 28 29 20 61 73 20 55 54 46 31 36 20 69 6e  16() as UTF16 in
20cc0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
20cd0 6f 72 64 65 72 2e 20 20 7b 46 31 36 34 31 34 7d  order.  {F16414}
20ce0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
20cf0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20d00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
20d10 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
20d20 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
20d30 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
20d40 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
20d50 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
20d60 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
20d70 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
20d80 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
20d90 74 65 72 2e 0a 2a 2a 20 7b 46 31 36 34 31 35 7d  ter..** {F16415}
20da0 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
20db0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
20dc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
20dd0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
20de0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
20df0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
20e00 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
20e10 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
20e20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
20e30 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
20e40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
20e50 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
20e60 67 65 2e 0a 2a 2a 20 7b 46 31 36 34 31 37 7d 20  ge..** {F16417} 
20e70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
20e80 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
20e90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
20ea0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
20eb0 6e 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  nes make a copy 
20ec0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
20ed0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
20ee0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
20ef0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 7b   they return.  {
20f00 45 4e 44 7d 20 48 65 6e 63 65 2c 20 74 68 65 20  END} Hence, the 
20f10 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
20f20 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
20f30 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
20f40 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
20f50 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
20f60 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  harm..**.** {F16
20f70 34 32 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33  421} The sqlite3
20f80 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
20f90 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
20fa0 73 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 74  s SQLite.** to t
20fb0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20 69 6e  hrow an error in
20fc0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
20fd0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
20fe0 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74 6f 20  s to long.** to 
20ff0 72 65 70 72 65 73 65 6e 74 2e 20 20 7b 46 31 36  represent.  {F16
21000 34 32 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33  422} The sqlite3
21010 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
21020 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63 61 75  interface.** cau
21030 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
21040 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
21050 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
21060 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   the a.** memory
21070 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
21080 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33  ed..**.** {F1643
21090 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  1} The sqlite3_r
210a0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
210b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
210c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
210d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
210e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
210f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
21100 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
21110 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
21120 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
21130 75 6d 65 6e 74 2e 0a 2a 2a 20 7b 46 31 36 34 33  ument..** {F1643
21140 32 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  2} The sqlite3_r
21150 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
21160 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
21170 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
21180 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
21190 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
211a0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
211b0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
211c0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
211d0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
211e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  rgument..**.** {
211f0 46 31 36 34 33 37 7d 20 54 68 65 20 73 71 6c 69  F16437} The sqli
21200 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
21210 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
21220 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
21230 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
21240 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
21250 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
21260 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ULL..**.** {F164
21270 34 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  41} The sqlite3_
21280 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
21290 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
212a0 78 74 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69  xt16(), .** sqli
212b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
212c0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
212d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
212e0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
212f0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
21300 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
21310 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
21320 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
21330 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
21340 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
21350 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
21360 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
21370 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
21380 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
21390 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
213a0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
213b0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 7b 46 31 36  ctively..** {F16
213c0 34 34 32 7d 20 53 51 4c 69 74 65 20 74 61 6b 65  442} SQLite take
213d0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
213e0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
213f0 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
21400 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
21410 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
21420 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
21430 65 72 66 61 63 65 73 2e 0a 2a 2a 20 7b 46 31 36  erfaces..** {F16
21440 34 34 34 7d 20 49 66 20 74 68 65 20 33 72 64 20  444} If the 3rd 
21450 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21460 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
21470 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
21480 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
21490 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
214a0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
214b0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
214c0 6d 65 74 65 72 20 0a 2a 2a 20 74 68 72 6f 75 67  meter .** throug
214d0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
214e0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 7b   character..** {
214f0 46 31 36 34 34 37 7d 20 49 66 20 74 68 65 20 33  F16447} If the 3
21500 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
21510 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
21520 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
21530 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
21540 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
21550 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
21560 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
21570 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
21580 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
21590 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
215a0 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
215b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
215c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
215d0 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20  lt..** {F16451} 
215e0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
215f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
21600 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
21610 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
21620 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
21630 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
21640 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
21650 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
21660 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
21670 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
21680 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
21690 20 62 6c 6f 62 20 72 65 73 75 6c 74 20 77 68 65   blob result whe
216a0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
216b0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
216c0 72 65 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34  result..** {F164
216d0 35 33 7d 20 49 66 20 74 68 65 20 34 74 68 20 70  53} If the 4th p
216e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
216f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
21700 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
21710 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
21720 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
21730 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
21740 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
21750 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
21760 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
21770 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72 65   text or blob re
21780 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e 74  sult is constant
21790 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64 6f   space and.** do
217a0 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68 65 20  es not copy the 
217b0 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20 61 20  space or call a 
217c0 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20  destructor when 
217d0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
217e0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
217f0 73 75 6c 74 2e 0a 2a 2a 20 7b 46 31 36 34 35 34  sult..** {F16454
21800 7d 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  } If the 4th par
21810 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
21820 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
21830 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
21840 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
21850 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
21860 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
21870 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
21880 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
21890 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
218a0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
218b0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
218c0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
218d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
218e0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
218f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 31 7d  ..**.** {F16461}
21900 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
21910 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
21920 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
21930 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
21940 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
21950 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
21960 62 65 20 61 20 63 6f 70 79 20 74 68 65 20 5b 73  be a copy the [s
21970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
21980 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
21990 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
219a0 61 6d 65 74 65 72 2e 20 20 7b 46 31 36 34 36 33  ameter.  {F16463
219b0 7d 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  } The.** sqlite3
219c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
219d0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
219e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
219f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
21a00 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69 74 65   so that [sqlite
21a10 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
21a20 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
21a30 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
21a40 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
21a50 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
21a60 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
21a70 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
21a80 20 68 61 72 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31   harm..**.** {U1
21a90 36 34 39 31 7d 20 54 68 65 73 65 20 72 6f 75 74  6491} These rout
21aa0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
21ab0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
21ac0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
21ad0 20 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e   .** than the on
21ae0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
21af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
21b00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
21b10 61 74 20 72 65 63 69 65 76 65 64 0a 2a 2a 20 74  at recieved.** t
21b20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
21b30 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
21b40 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
21b50 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
21b60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
21b70 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
21b80 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
21b90 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
21ba0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
21bb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
21bc0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
21bd0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
21be0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
21bf0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
21c00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
21c10 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
21c20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
21c30 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
21c40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
21c50 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
21c60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
21c70 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
21c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
21c90 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
21ca0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
21cb0 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
21cc0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
21cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
21ce0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
21cf0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
21d00 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
21d10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
21d20 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
21d30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
21d40 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
21d50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
21d60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
21d70 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
21d80 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
21d90 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
21da0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
21db0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
21dc0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
21dd0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
21de0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
21df0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
21e00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
21e10 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
21e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
21e30 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
21e40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
21e50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
21e60 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
21e70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
21e80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
21e90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
21ea0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
21eb0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
21ec0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
21ed0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
21ee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
21ef0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
21f00 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
21f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21f20 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
21f30 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
21f40 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a  es {F16600}.**.*
21f50 2a 20 7b 46 31 36 36 30 31 7d 0a 2a 2a 20 54 68  * {F16601}.** Th
21f60 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
21f70 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
21f80 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
21f90 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
21fa0 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e 64 6c  [sqlite3*] handl
21fb0 65 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  e specified as t
21fc0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21fd0 74 2e 20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  t. .**.** {F1660
21fe0 32 7d 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  2}.** The name o
21ff0 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74  f the new collat
22000 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
22010 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55  specified as a U
22020 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
22030 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
22040 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
22050 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
22060 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
22070 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
22080 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74  string for sqlit
22090 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
220a0 69 6f 6e 31 36 28 29 2e 20 7b 46 31 36 36 30 33  ion16(). {F16603
220b0 7d 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a  } In all cases.*
220c0 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
220d0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
220e0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
220f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ment..**.** {F16
22100 36 30 34 7d 0a 2a 2a 20 54 68 65 20 74 68 69 72  604}.** The thir
22110 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  d argument may b
22120 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
22130 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55  stants [SQLITE_U
22140 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  TF8],.** [SQLITE
22150 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51  _UTF16LE] or [SQ
22160 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
22170 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
22180 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
22190 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
221a0 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
221b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
221c0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
221d0 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
221e0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
221f0 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  n or UTF-16 big-
22200 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
22210 65 6c 79 2e 20 7b 46 31 36 36 30 35 7d 20 54 68  ely. {F16605} Th
22220 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
22230 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
22240 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
22250 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
22260 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
22270 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
22280 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
22290 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
222a0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
222b0 54 46 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  TF16 in the nati
222c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f 66  ve byte order of
222d0 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
222e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  er..**.** {F1660
222f0 37 7d 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  7}.** A pointer 
22300 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
22310 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
22320 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
22330 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
22340 6d 65 6e 74 2e 20 7b 46 31 36 36 30 39 7d 20 49  ment. {F16609} I
22350 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
22360 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
22370 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
22380 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
22390 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
223a0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
223b0 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
223c0 20 7b 46 31 36 36 31 31 7d 20 45 61 63 68 20 74   {F16611} Each t
223d0 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
223e0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
223f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
22400 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
22410 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
22420 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 0a  void* passed as.
22430 2a 2a 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  ** the fourth ar
22440 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
22450 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
22460 6f 6e 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  on() or.** sqlit
22470 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
22480 69 6f 6e 31 36 28 29 20 61 73 20 69 74 73 20 66  ion16() as its f
22490 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
224a0 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 0a 2a  **.** {F16612}.*
224b0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
224c0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
224d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
224e0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
224f0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
22500 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
22510 65 64 20 62 79 20 61 20 5b 6c 65 6e 67 74 68 2c  ed by a [length,
22520 20 64 61 74 61 5d 20 70 61 69 72 20 61 6e 64 20   data] pair and 
22530 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
22540 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
22550 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
22560 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
22570 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
22580 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
22590 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
225a0 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63  {END} The applic
225b0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
225c0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
225d0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
225e0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
225f0 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a  or positive if.*
22600 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  * the first stri
22610 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
22620 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
22630 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
22640 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e  econd.** string.
22650 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
22660 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
22670 20 7b 46 31 36 36 31 35 7d 0a 2a 2a 20 54 68 65   {F16615}.** The
22680 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
22690 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
226a0 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
226b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
226c0 6f 6e 28 29 0a 2a 2a 20 65 78 63 61 70 74 20 74  on().** excapt t
226d0 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
226e0 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
226f0 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
22700 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
22710 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 7b 46 31 36  collation.  {F16
22720 36 31 37 7d 20 54 68 65 20 64 65 73 74 72 75 63  617} The destruc
22730 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
22740 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
22750 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
22760 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
22770 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
22780 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
22790 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
227a0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
227b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
227c0 32 28 29 2e 0a 2a 2a 20 7b 46 31 36 36 31 38 7d  2()..** {F16618}
227d0 20 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65    Collations are
227e0 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a   destroyed when.
227f0 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  ** they are over
22800 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20  ridden by later 
22810 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
22820 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
22830 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20  functions.** or 
22840 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  when the [sqlite
22850 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e  3*] database han
22860 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73  dle is closed us
22870 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
22880 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
22890 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
228a0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
228b0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
228c0 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
228d0 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
228e0 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
228f0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
22900 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
22910 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
22920 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
22930 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
22940 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
22950 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
22960 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
22970 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
22980 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
22990 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
229a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
229b0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
229c0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
229d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
229e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
229f0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
22a00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
22a10 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
22a20 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
22a30 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
22a40 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
22a50 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
22a60 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
22a70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
22a80 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
22a90 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a  lbacks {F16700}.
22aa0 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 31 7d 0a 2a  **.** {F16701}.*
22ab0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
22ac0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
22ad0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
22ae0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
22af0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
22b00 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
22b10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22b20 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
22b30 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
22b40 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
22b50 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
22b60 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
22b70 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
22b80 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71  quence is.** req
22b90 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  uired..**.** {F1
22ba0 36 37 30 32 7d 0a 2a 2a 20 49 66 20 74 68 65 20  6702}.** If the 
22bb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
22bc0 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
22bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
22be0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
22bf0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
22c00 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
22c10 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
22c20 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
22c30 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
22c40 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
22c50 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {F16703} If sql
22c60 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
22c70 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
22c80 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a 20  d, the names.** 
22c90 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
22ca0 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
22cb0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
22cc0 72 2e 20 7b 46 31 36 37 30 34 7d 20 41 20 63 61  r. {F16704} A ca
22cd0 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ll to either.** 
22ce0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
22cf0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
22d00 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
22d10 46 31 36 37 30 35 7d 20 57 68 65 6e 20 74 68 65  F16705} When the
22d20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22d30 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
22d40 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
22d50 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
22d60 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
22d70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
22d80 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
22d90 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
22da0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
22db0 31 36 28 29 2e 20 7b 46 31 36 37 30 36 7d 20 54  16(). {F16706} T
22dc0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
22dd0 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
22de0 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 7b  se.** handle.  {
22df0 46 31 36 37 30 37 7d 20 54 68 65 20 74 68 69 72  F16707} The thir
22e00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
22e10 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
22e20 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
22e30 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
22e40 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
22e50 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
22e60 74 0a 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66  t.** desirable f
22e70 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
22e80 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75  tion sequence fu
22e90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
22ea0 0a 2a 2a 20 7b 46 31 36 37 30 38 7d 20 54 68 65  .** {F16708} The
22eb0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22ec0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
22ed0 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
22ee0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
22ef0 6e 63 65 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  nce. {END}.**.**
22f00 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
22f10 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
22f20 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
22f30 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
22f40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
22f50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
22f60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
22f70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
22f80 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
22f90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
22fa0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
22fb0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
22fc0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
22fd0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
22fe0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
22ff0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
23000 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
23010 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
23020 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
23030 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
23040 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
23050 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
23060 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
23070 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
23080 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
23090 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
230a0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
230b0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
230c0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
230d0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
230e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
230f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
23100 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
23110 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
23120 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
23130 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
23140 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
23150 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
23160 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
23170 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
23180 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
23190 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
231a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
231b0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
231c0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
231d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
231e0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
231f0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
23200 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
23210 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
23220 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
23230 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
23240 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
23250 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
23260 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
23270 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
23280 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
23290 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
232a0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
232b0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
232c0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
232d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
232e0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
232f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23310 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
23320 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
23330 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
23340 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
23350 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
23360 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
23370 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20 45 78  REF:  Suspend Ex
23380 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
23390 6f 72 74 20 54 69 6d 65 20 7b 46 31 30 35 33 30  ort Time {F10530
233a0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 31 7d  }.**.** {F10531}
233b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
233c0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ep() function.**
233d0 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
233e0 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
233f0 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
23400 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
23410 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
23420 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
23430 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
23440 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35  ter..**.** {F105
23450 33 32 7d 20 49 66 20 74 68 65 20 6f 70 65 72 61  32} If the opera
23460 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
23470 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
23480 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
23490 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
234a0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
234b0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
234c0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
234d0 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
234e0 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 7b 46  arest second. {F
234f0 31 30 35 33 33 7d 20 54 68 65 20 6e 75 6d 62 65  10533} The numbe
23500 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
23510 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
23520 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74 65  lly .** requeste
23530 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
23540 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
23550 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
23560 46 31 30 35 33 34 7d 20 53 51 4c 69 74 65 20 69  F10534} SQLite i
23570 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
23580 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
23590 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
235a0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
235b0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
235c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
235d0 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  {END}.*/.int sql
235e0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
235f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23600 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  :  Name Of The F
23610 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
23620 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 46  mporary Files {F
23630 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20  10310}.**.** If 
23640 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
23650 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
23660 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
23670 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
23680 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
23690 65 72 20 28 61 2e 6b 61 2e 20 64 69 72 65 63 74  er (a.ka. direct
236a0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
236b0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
236c0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
236d0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
236e0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
236f0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
23700 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55  ariable.** is NU
23710 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
23720 20 53 51 4c 69 74 65 20 64 6f 65 73 20 61 20 73   SQLite does a s
23730 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
23740 72 6f 70 72 69 61 74 65 20 74 65 6d 70 6f 72 61  ropriate tempora
23750 72 79 0a 2a 2a 20 66 69 6c 65 20 64 69 72 65 63  ry.** file direc
23760 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
23770 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
23780 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
23790 6c 65 20 6f 6e 63 65 20 61 20 64 61 74 61 62 61  le once a databa
237a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
237b0 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64   has been opened
237c0 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  .  It is intende
237d0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
237e0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
237f0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
23800 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
23810 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
23820 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
23830 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
23840 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
23850 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68   and remain unch
23860 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65 72  anged thereafter
23870 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
23880 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
23890 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
238a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
238b0 3a 20 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  :  Test To See I
238c0 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
238d0 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
238e0 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a   Mode {F12930}.*
238f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23900 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
23910 29 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ) interfaces ret
23920 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
23930 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
23940 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
23950 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
23960 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
23970 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
23980 73 70 65 63 74 69 76 65 6c 79 2e 20 20 20 41 75  spectively.   Au
23990 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
239a0 20 6f 6e 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c   on.** by defaul
239b0 74 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  t.  Autocommit m
239c0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
239d0 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
239e0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
239f0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
23a00 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
23a10 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
23a20 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
23a30 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
23a40 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
23a50 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
23a60 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
23a70 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
23a80 6f 6e 73 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ons (errors incl
23a90 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
23aa0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
23ab0 52 52 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  RR], .** [SQLITE
23ac0 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
23ad0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
23ae0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
23af0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
23b00 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
23b10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
23b20 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
23b30 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
23b40 66 69 6e 64 20 6f 75 74 20 69 66 20 53 51 4c 69  find out if SQLi
23b50 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
23b60 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
23b70 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
23b80 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
23b90 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
23ba0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
23bb0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
23bc0 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71  {F12931} The [sq
23bd0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
23be0 6d 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  mmit()] interfac
23bf0 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
23c00 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ro or.**        
23c10 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69    zero if the gi
23c20 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
23c30 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
23c40 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
23c50 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  it.**          m
23c60 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ode, respectivel
23c70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32  y..**.** {F12932
23c80 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
23c90 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
23ca0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33  lt..**.** {F1293
23cb0 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  3} Autocommit mo
23cc0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
23cd0 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
23ce0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
23cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d  ..**.** {F12934}
23d00 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
23d10 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61   is enabled by a
23d20 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d   successful [COM
23d30 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
23d40 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  K].**          s
23d50 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a  tatement..** .**
23d60 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
23d70 0a 2a 2a 2a 0a 2a 2a 20 7b 55 31 32 39 33 36 7d  .***.** {U12936}
23d80 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
23d90 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
23da0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
23db0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
23dd0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
23de0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
23df0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
23e00 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
23e10 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
23e20 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
23e30 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
23e40 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
23e50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23e60 20 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62    Find The Datab
23e70 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
23e80 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23e90 6e 74 20 7b 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a  nt {F13120}.**.*
23ea0 2a 20 7b 46 31 33 31 32 31 7d 20 54 68 65 20 73  * {F13121} The s
23eb0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
23ec0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
23ed0 74 75 72 6e 73 20 74 68 65 20 5b 73 71 6c 69 74  turns the [sqlit
23ee0 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
23ef0 6e 64 6c 65 20 74 6f 20 77 68 69 63 68 20 61 0a  ndle to which a.
23f00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  ** [sqlite3_stmt
23f10 20 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74   | prepared stat
23f20 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a  ement] belongs..
23f30 2a 2a 20 7b 46 31 33 31 32 32 7d 20 74 68 65 20  ** {F13122} the 
23f40 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
23f50 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
23f60 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 0a 2a 2a  te3_db_handle.**
23f70 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74   is the same dat
23f80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61  abase handle tha
23f90 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66 69 72  t was.** the fir
23fa0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
23fb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
23fc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
23fd0 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74 68 61   variants.** tha
23fe0 74 20 77 61 73 20 75 73 65 64 20 74 6f 20 63 72  t was used to cr
23ff0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
24000 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
24010 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
24020 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
24030 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
24040 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t*);.../*.** CAP
24050 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
24060 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
24070 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
24080 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a  s {F12950}.**.**
24090 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20 73 71   {F12951} The sq
240a0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
240b0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
240c0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
240d0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
240e0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
240f0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
24100 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
24110 2e 0a 2a 2a 20 7b 46 31 32 39 35 32 7d 20 41 6e  ..** {F12952} An
24120 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
24130 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
24140 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
24150 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
24160 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
24170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24180 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
24190 20 7b 46 31 32 39 35 33 7d 20 54 68 65 20 73 71   {F12953} The sq
241a0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
241b0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
241c0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
241d0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
241e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
241f0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
24200 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
24210 65 64 2e 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20  ed..** {F12954} 
24220 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
24230 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
24240 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
24250 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
24260 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
24270 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24280 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
24290 2a 2a 20 7b 46 31 32 39 35 36 7d 20 54 68 65 20  ** {F12956} The 
242a0 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73  pArg argument is
242b0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
242c0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
242d0 63 6b 2e 20 20 7b 46 31 32 39 35 37 7d 20 49 66  ck.  {F12957} If
242e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
242f0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
24300 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 72 65 74 75  unction .** retu
24310 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
24320 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
24330 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
24340 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
24350 2a 20 7b 46 31 32 39 35 38 7d 20 49 66 20 61 6e  * {F12958} If an
24360 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
24370 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
24380 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a  gistered, its.**
24390 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
243a0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
243b0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
243c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  rned..**.** {F12
243d0 39 35 39 7d 20 52 65 67 69 73 74 65 72 69 6e 67  959} Registering
243e0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
243f0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
24400 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46  llback..**.** {F
24410 31 32 39 36 31 7d 20 46 6f 72 20 74 68 65 20 70  12961} For the p
24420 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
24430 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
24440 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
24450 76 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c  ve been .** roll
24460 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
24470 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
24480 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
24490 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
244a0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
244b0 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
244c0 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
244d0 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 7b  k to occur..** {
244e0 46 31 32 39 36 32 7d 20 54 68 65 20 72 6f 6c 6c  F12962} The roll
244f0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
24500 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
24510 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
24520 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
24530 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
24540 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
24550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
24560 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 7b 46 31 32   closed..** {F12
24570 39 36 34 7d 20 54 68 65 20 72 6f 6c 6c 62 61 63  964} The rollbac
24580 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
24590 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
245a0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
245b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
245c0 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63 61  ause a commit ca
245d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64 20  llback returned 
245e0 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f  non-zero..** <to
245f0 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68 69  do> Check on thi
24600 73 20 3c 2f 74 6f 64 6f 3e 20 7b 45 4e 44 7d 0a  s </todo> {END}.
24610 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
24620 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
24630 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20  erfaces and are 
24640 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
24650 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
24660 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
24670 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
24680 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
24690 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
246a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
246b0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
246c0 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
246d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
246e0 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
246f0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
24700 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a  cks {F12970}.**.
24710 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54 68 65 20  ** {F12971} The 
24720 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
24730 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ook() interface.
24740 2a 2a 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ** registers a c
24750 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
24760 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
24770 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64  se connection id
24780 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
24790 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75 6d 65  .** first argume
247a0 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  nt to be invoked
247b0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
247c0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
247d0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
247e0 0a 2a 2a 20 7b 46 31 32 39 37 32 7d 20 41 6e 79  .** {F12972} Any
247f0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
24800 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
24810 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
24820 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a  n for the same .
24830 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
24840 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
24850 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  dden..**.** {F12
24860 39 37 34 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  974} The second 
24870 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24880 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
24890 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
248a0 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20 69  when a .** row i
248b0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
248c0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 20  ted or deleted. 
248d0 0a 2a 2a 20 7b 46 31 32 39 37 36 7d 20 54 68 65  .** {F12976} The
248e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
248f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
24900 69 73 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20  is.** a copy of 
24910 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
24920 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  nt to sqlite3_up
24930 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20  date_hook()..** 
24940 7b 46 31 32 39 37 37 7d 20 54 68 65 20 73 65 63  {F12977} The sec
24950 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ond callback .**
24960 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
24970 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
24980 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
24990 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ETE] or [SQLITE_
249a0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65  UPDATE],.** depe
249b0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
249c0 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
249d0 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ed the callback 
249e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
249f0 2a 20 7b 46 31 32 39 37 38 7d 20 54 68 65 20 74  * {F12978} The t
24a00 68 69 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75  hird and .** fou
24a10 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
24a20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
24a30 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
24a40 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  o the database a
24a50 6e 64 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d  nd .** table nam
24a60 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
24a70 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
24a80 2a 20 7b 46 31 32 39 37 39 7d 20 54 68 65 20 66  * {F12979} The f
24a90 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
24aa0 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a 20 74  rameter is .** t
24ab0 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
24ac0 72 6f 77 2e 0a 2a 2a 20 7b 46 31 32 39 38 31 7d  row..** {F12981}
24ad0 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   In the case of 
24ae0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
24af0 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74  is the rowid aft
24b00 65 72 20 0a 2a 2a 20 74 68 65 20 75 70 64 61 74  er .** the updat
24b10 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
24b20 2a 0a 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68  *.** {F12983} Th
24b30 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
24b40 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
24b50 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
24b60 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
24b70 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
24b80 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
24b90 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
24ba0 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 34  )..**.** {F12984
24bb0 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e  } If another fun
24bc0 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f  ction was previo
24bd0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c  usly registered,
24be0 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65 0a   its pArg value.
24bf0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ** is returned. 
24c00 20 7b 46 31 32 39 38 35 7d 20 4f 74 68 65 72 77   {F12985} Otherw
24c10 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
24c20 72 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  rned..*/.void *s
24c30 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
24c40 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
24c50 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
24c60 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
24c70 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
24c80 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
24c90 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
24ca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 6e  ** CAPI3REF:  En
24cb0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
24cc0 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
24cd0 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 0a 2a  he {F10330}.**.*
24ce0 2a 20 7b 46 31 30 33 33 31 7d 0a 2a 2a 20 54 68  * {F10331}.** Th
24cf0 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
24d00 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
24d10 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
24d20 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
24d30 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
24d40 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
24d50 65 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f  etween connectio
24d60 6e 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ns to the same d
24d70 61 74 61 62 61 73 65 2e 0a 2a 2a 20 7b 46 31 30  atabase..** {F10
24d80 33 33 32 7d 0a 2a 2a 20 53 68 61 72 69 6e 67 20  332}.** Sharing 
24d90 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
24da0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
24db0 75 65 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ue and disabled 
24dc0 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  if the argument.
24dd0 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  ** is false..**.
24de0 2a 2a 20 7b 46 31 30 33 33 33 7d 20 43 61 63 68  ** {F10333} Cach
24df0 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
24e00 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
24e10 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69  d.** for an enti
24e20 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44  re process. {END
24e30 7d 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  } This is a chan
24e40 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
24e50 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a  version 3.5.0..*
24e60 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  * In prior versi
24e70 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73  ons of SQLite, s
24e80 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e  haring was.** en
24e90 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
24ea0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
24eb0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
24ec0 0a 2a 2a 20 7b 46 31 30 33 33 34 7d 0a 2a 2a 20  .** {F10334}.** 
24ed0 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
24ee0 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
24ef0 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
24f00 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
24f10 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
24f20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
24f30 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
24f40 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
24f50 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
24f60 2a 20 7b 46 31 30 33 33 35 7d 20 45 78 69 73 74  * {F10335} Exist
24f70 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
24f80 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
24f90 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
24fa0 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
24fb0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
24fc0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
24fd0 72 65 20 6f 70 65 6e 65 64 2e 20 7b 45 4e 44 7d  re opened. {END}
24fe0 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
24ff0 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20  ables cannot be 
25000 75 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72  used with a shar
25010 65 64 20 63 61 63 68 65 2e 20 20 7b 46 31 30 33  ed cache.  {F103
25020 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 0a  36} When shared.
25030 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
25040 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
25050 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
25060 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
25070 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
25080 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
25090 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
250a0 65 72 72 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  error. {END}.**.
250b0 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54 68 69 73  ** {F10337} This
250c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
250d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
250e0 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
250f0 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  .** enabled or d
25100 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66  isabled successf
25110 75 6c 6c 79 2e 20 20 7b 46 31 30 33 33 38 7d 20  ully.  {F10338} 
25120 41 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  An [SQLITE_ERROR
25130 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a   | error code].*
25140 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  * is returned ot
25150 68 65 72 77 69 73 65 2e 20 7b 45 4e 44 7d 0a 2a  herwise. {END}.*
25160 2a 0a 2a 2a 20 7b 46 31 30 33 33 39 7d 20 53 68  *.** {F10339} Sh
25170 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
25180 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
25190 74 2e 20 7b 45 4e 44 7d 20 42 75 74 20 74 68 69  t. {END} But thi
251a0 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
251b0 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
251c0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
251d0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
251e0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
251f0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
25200 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
25210 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
25220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
25230 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
25240 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
25250 43 41 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d  CAPI3REF:  Attem
25260 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
25270 4d 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a  Memory {F17340}.
25280 2a 2a 0a 2a 2a 20 7b 46 31 37 33 34 31 7d 20 54  **.** {F17341} T
25290 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
252a0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
252b0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
252c0 6f 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65  o.** free N byte
252d0 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  s of heap memory
252e0 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
252f0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
25300 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
25310 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65  ions held by the
25320 20 64 61 74 61 62 61 73 65 20 6c 61 62 72 61 72   database labrar
25330 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79  y. {END}  Memory
25340 20 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68   used.** to cach
25350 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73  e database pages
25360 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
25370 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
25380 61 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d  ample of.** non-
25390 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
253a0 2e 20 20 7b 46 31 36 33 34 32 7d 20 73 71 6c 69  .  {F16342} sqli
253b0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
253c0 72 79 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ry() returns.** 
253d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
253e0 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
253f0 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20  ed, which might 
25400 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a  be more or less.
25410 2a 2a 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ** than the amou
25420 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
25430 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
25440 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
25450 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25460 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
25470 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20  it On Heap Size 
25480 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 7b  {F17350}.**.** {
25490 46 31 36 33 35 31 7d 20 54 68 65 20 73 71 6c 69  F16351} The sqli
254a0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
254b0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  mit() interface.
254c0 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ** places a "sof
254d0 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  t" limit on the 
254e0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
254f0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
25500 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20 62  e allocated.** b
25510 79 20 53 51 4c 69 74 65 2e 20 7b 46 31 36 33 35  y SQLite. {F1635
25520 32 7d 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  2} If an interna
25530 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
25540 72 65 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68  requested .** th
25550 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20  at would exceed 
25560 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
25570 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  mit, [sqlite3_re
25580 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
25590 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e  is.** invoked on
255a0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
255b0 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20  to free up some 
255c0 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65  space before the
255d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
255e0 73 20 6d 61 64 65 2e 20 7b 45 4e 44 7d 0a 2a 2a  s made. {END}.**
255f0 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 54 68 65  .** {F16353} The
25600 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
25610 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
25620 20 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   if.** [sqlite3_
25630 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
25640 5d 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65  ] cannot.** free
25650 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
25660 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ry to prevent th
25670 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69  e limit from bei
25680 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20  ng exceeded,.** 
25690 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  the memory is al
256a0 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61  located anyway a
256b0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f  nd the current o
256c0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
256d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34  s..**.** {F16354
256e0 7d 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  }.** A negative 
256f0 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
25700 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
25710 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
25720 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
25730 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
25740 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
25750 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
25760 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
25770 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 7b 46  exhausted..** {F
25780 31 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75  16355} The defau
25790 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
257a0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
257b0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   is zero..**.** 
257c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62  SQLite makes a b
257d0 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f  est effort to ho
257e0 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  nor the soft hea
257f0 70 20 6c 69 6d 69 74 2e 20 20 0a 2a 2a 20 7b 46  p limit.  .** {F
25800 31 36 33 35 36 7d 20 42 75 74 20 69 66 20 74 68  16356} But if th
25810 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
25820 74 20 63 61 6e 6e 6f 74 20 68 6f 6e 6f 72 65 64  t cannot honored
25830 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
25840 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
25850 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
25860 74 69 66 69 63 61 74 69 6f 6e 2e 20 7b 45 4e 44  tification. {END
25870 7d 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74  }  This is why t
25880 68 65 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20  he limit is .** 
25890 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20  called a "soft" 
258a0 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64  limit.  It is ad
258b0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
258c0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
258d0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
258e0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  , this routine o
258f0 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20  nly constrained 
25900 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
25910 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e  located by a sin
25920 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65  gle thread - the
25930 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
25940 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69  which this routi
25950 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67  ne.** runs.  Beg
25960 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
25970 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
25980 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
25990 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c  limit is.** appl
259a0 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61  ied to all threa
259b0 64 73 2e 20 7b 46 31 36 33 35 37 7d 20 54 68 65  ds. {F16357} The
259c0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
259d0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
259e0 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
259f0 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
25a00 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
25a10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
25a20 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 7b 45   all threads. {E
25a30 4e 44 7d 20 20 49 6e 0a 2a 2a 20 76 65 72 73 69  ND}  In.** versi
25a40 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69  on 3.5.0 there i
25a50 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66  s no mechanism f
25a60 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20  or limiting the 
25a70 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a  heap usage for.*
25a80 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72  * individual thr
25a90 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  eads..*/.void sq
25aa0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
25ab0 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  limit(int);../*.
25ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78  ** CAPI3REF:  Ex
25ad0 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
25ae0 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
25af0 20 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30   A Table {F12850
25b00 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
25b10 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tine.** returns 
25b20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20  meta-data about 
25b30 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
25b40 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20  n of a specific 
25b50 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c  database.** tabl
25b60 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
25b70 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ng the connectio
25b80 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20  n handle passed 
25b90 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
25ba0 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65  ction .** argume
25bb0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  nt..**.** The co
25bc0 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
25bd0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
25be0 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
25bf0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
25c00 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69   .** this functi
25c10 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  on. The second p
25c20 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
25c30 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
25c40 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
25c50 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
25c60 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68  mp" or an attach
25c70 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
25c80 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
25c90 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
25ca0 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73  r NULL. If it is
25cb0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
25cc0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
25cd0 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
25ce0 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
25cf0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
25d00 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65  algorithm as the
25d10 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
25d20 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73   uses to .** res
25d30 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
25d40 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
25d50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  s..**.** The thi
25d60 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
25d70 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
25d80 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
25d90 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
25da0 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  mn .** name of t
25db0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
25dc0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
25dd0 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
25de0 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a  e parameters .**
25df0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
25e00 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61  .** Meta informa
25e10 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  tion is returned
25e20 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
25e30 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
25e40 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a  ons passed as.**
25e50 20 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62   the 5th and sub
25e60 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
25e70 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
25e80 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73  ion. Any of thes
25e90 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  e .** arguments 
25ea0 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20  may be NULL, in 
25eb0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
25ec0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
25ed0 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a  ment of meta .**
25ee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
25ef0 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommitted..**.** 
25f00 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74  <pre>.** Paramet
25f10 65 72 20 20 20 20 20 4f 75 74 70 75 74 20 54 79  er     Output Ty
25f20 70 65 20 20 20 20 20 20 44 65 73 63 72 69 70 74  pe      Descript
25f30 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d  ion.** ---------
25f40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
25f50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a  ----------.**.**
25f60 20 20 20 35 74 68 20 20 20 20 20 20 20 20 20 63     5th         c
25f70 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
25f80 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36  Data type.**   6
25f90 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  th         const
25fa0 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65   char*      Name
25fb0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
25fc0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
25fd0 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20  ce .**   7th    
25fe0 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20       int        
25ff0 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68        True if th
26000 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  e column has a N
26010 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
26020 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20  nt.**   8th     
26030 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
26040 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
26050 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
26060 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
26070 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20  EY.**   9th     
26080 20 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20      int         
26090 20 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65       True if the
260a0 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49   column is AUTOI
260b0 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72  NCREMENT.** </pr
260c0 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e>.**.**.** The 
260d0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
260e0 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
260f0 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
26100 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a  rned for the .**
26110 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
26120 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
26130 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
26140 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
26150 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74   next .** call t
26160 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49  o any sqlite API
26170 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
26180 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
26190 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
261a0 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e  lly a view, then
261b0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
261c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  urned..**.** If 
261d0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
261e0 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
261f0 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
26200 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49  d_" and an .** I
26210 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
26220 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  EY column has be
26230 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
26240 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
26250 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61   output .** para
26260 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
26270 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
26280 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
26290 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  n. If there is n
262a0 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20  o.** explicitly 
262b0 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c  declared IPK col
262c0 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
262d0 74 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  tput parameters 
262e0 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66  are set as .** f
262f0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
26300 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
26310 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
26320 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
26330 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
26340 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
26350 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
26360 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
26370 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
26380 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a  nt: 0.** </pre>.
26390 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
263a0 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
263b0 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
263c0 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
263d0 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
263e0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
263f0 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
26400 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
26410 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
26420 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
26430 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49  e found, an SQLI
26440 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  TE error code is
26450 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e   returned and an
26460 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
26470 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61  * left in the da
26480 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74  tabase handle (t
26490 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
264a0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
264b0 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
264c0 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
264d0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
264e0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
264f0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
26500 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
26510 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70  OLUMN_METADATA p
26520 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
26530 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
26540 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
26550 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
26560 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26580 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
26590 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
265a0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
265b0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
265c0 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
265d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
265e0 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
265f0 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
26600 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
26610 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
26620 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
26630 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
26640 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
26650 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
26660 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
26670 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
26680 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
26690 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
266a0 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
266b0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
266c0 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
266d0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
266e0 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
266f0 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
26700 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
26710 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
26720 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
26730 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
26740 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
26750 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
26760 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
26770 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
26780 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
26790 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
267a0 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
267b0 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32  n Extension {F12
267c0 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  600}.**.** {F126
267d0 30 31 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  01} The sqlite3_
267e0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
267f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74   interface.** at
26800 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
26810 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
26820 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
26830 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
26840 0a 2a 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36  .** zFile. {F126
26850 30 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f  02} The entry po
26860 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46  int is zProc. {F
26870 31 32 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79  12603} zProc may
26880 20 62 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63   be 0.** in whic
26890 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
268a0 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
268b0 6e 74 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74  nt defaults.** t
268c0 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
268d0 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a  sion_init"..**.*
268e0 2a 20 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73  * {F12604} The s
268f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
26900 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
26910 65 20 73 68 61 6c 6c 0a 2a 2a 20 72 65 74 75 72  e shall.** retur
26920 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
26930 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
26940 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
26950 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
26960 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36  ong..**.** {F126
26970 30 35 7d 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72  05}.** If an err
26980 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
26990 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
269a0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 73 71 6c   then the.** sql
269b0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
269c0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
269d0 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
269e0 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
269f0 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72 20 6d  with .** error m
26a00 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72  essage text stor
26a10 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ed in memory obt
26a20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
26a30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
26a40 2a 20 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c  * {END}  The cal
26a50 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
26a60 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
26a70 65 6d 6f 72 79 0a 2a 2a 20 62 79 20 63 61 6c 6c  emory.** by call
26a80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
26a90 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  e()]..**.** {F12
26aa0 36 30 36 7d 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  606}.** Extensio
26ab0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
26ac0 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  e enabled using 
26ad0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
26ae0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
26af0 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  ].** prior to ca
26b00 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 20 6f  lling this API o
26b10 72 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  r an error will 
26b20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a  be returned..*/.
26b30 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
26b40 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
26b50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26b60 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
26b70 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
26b80 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
26b90 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
26ba0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
26bb0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
26bc0 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
26bd0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
26be0 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
26bf0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
26c00 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
26c10 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
26c20 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
26c30 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
26c40 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
26c50 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
26c60 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
26c70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
26c80 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
26c90 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
26ca0 69 6e 67 20 7b 46 31 32 36 32 30 7d 0a 2a 2a 0a  ing {F12620}.**.
26cb0 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  ** So as not to 
26cc0 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
26cd0 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
26ce0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
26cf0 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
26d00 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
26d10 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
26d20 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
26d30 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
26d40 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
26d50 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
26d60 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
26d70 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
26d80 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70 72 6f  ng.** API is pro
26d90 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
26da0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
26db0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
26dc0 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a 2a 2a  hanism on and.**
26dd0 20 6f 66 66 2e 20 20 7b 46 31 32 36 32 32 7d 20   off.  {F12622} 
26de0 49 74 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  It is off by def
26df0 61 75 6c 74 2e 20 7b 45 4e 44 7d 20 53 65 65 20  ault. {END} See 
26e00 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
26e10 0a 2a 2a 20 7b 46 31 32 36 32 31 7d 20 43 61 6c  .** {F12621} Cal
26e20 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
26e30 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
26e40 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  ion() routine.**
26e50 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 20 74   with onoff==1 t
26e60 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
26e70 20 6c 6f 61 64 69 6e 67 20 6f 6e 0a 2a 2a 20 61   loading on.** a
26e80 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
26e90 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
26ea0 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
26eb0 69 6e 2e 20 7b 45 4e 44 7d 0a 2a 2f 0a 69 6e 74  in. {END}.*/.int
26ec0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
26ed0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
26ee0 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
26ef0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
26f00 41 50 49 33 52 45 46 3a 20 4d 61 6b 65 20 41 72  API3REF: Make Ar
26f10 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f 20 41 75  rangements To Au
26f20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
26f30 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20 7b 46   An Extension {F
26f40 31 32 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31  12640}.**.** {F1
26f50 32 36 34 31 7d 20 54 68 69 73 20 66 75 6e 63 74  2641} This funct
26f60 69 6f 6e 0a 2a 2a 20 72 65 67 69 73 74 65 72 73  ion.** registers
26f70 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e   an extension en
26f80 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69  try point that i
26f90 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
26fa0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65  invoked.** whene
26fb0 76 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  ver a new databa
26fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
26fd0 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a   opened using.**
26fe0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
26ff0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
27000 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
27010 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 7b  e3_open_v2()]. {
27020 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
27030 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
27040 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
27050 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
27060 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
27070 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
27080 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
27090 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
270a0 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
270b0 20 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61   to all new data
270c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
270d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 32 7d  ..**.** {F12642}
270e0 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
270f0 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
27100 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
27110 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
27120 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
27130 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
27140 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
27150 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 34 33 7d  ..**.** {F12643}
27160 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   This routine st
27170 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ores a pointer t
27180 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  o the extension 
27190 69 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 74  in an array.** t
271a0 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
271b0 66 72 6f 6d 20 73 71 6c 69 74 65 5f 6d 61 6c 6c  from sqlite_mall
271c0 6f 63 28 29 2e 20 7b 45 4e 44 7d 20 49 66 20 79  oc(). {END} If y
271d0 6f 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20  ou run a memory 
271e0 6c 65 61 6b 0a 2a 2a 20 63 68 65 63 6b 65 72 20  leak.** checker 
271f0 6f 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20  on your program 
27200 61 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61  and it reports a
27210 20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66   leak because of
27220 20 74 68 69 73 0a 2a 2a 20 61 72 72 61 79 2c 20   this.** array, 
27230 74 68 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  then invoke [sql
27240 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
27250 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
27260 6f 72 0a 2a 2a 20 74 6f 20 73 68 75 74 64 6f 77  or.** to shutdow
27270 6e 20 74 6f 20 66 72 65 65 20 74 68 65 20 6d 65  n to free the me
27280 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  mory..**.** {F12
27290 36 34 34 7d 20 41 75 74 6f 6d 61 74 69 63 20 65  644} Automatic e
272a0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
272b0 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
272c0 64 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ds. {END}.**.** 
272d0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
272e0 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  s experimental a
272f0 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
27300 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65   change or.** re
27310 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
27320 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
27330 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
27340 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
27350 6e 28 76 6f 69 64 20 2a 78 45 6e 74 72 79 50 6f  n(void *xEntryPo
27360 69 6e 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  int);.../*.** CA
27370 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
27380 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
27390 6e 20 4c 6f 61 64 69 6e 67 20 7b 46 31 32 36 36  n Loading {F1266
273a0 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 36 31  0}.**.** {F12661
273b0 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
273c0 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
273d0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
273e0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20  ed.** automatic 
273f0 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44  extensions. {END
27400 7d 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75 74 69  }  This.** routi
27410 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
27420 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
27430 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 6d  r [sqlite3_autom
27440 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e 28 29  atic_extension()
27450 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  ].** calls..**.*
27460 2a 20 7b 46 31 32 36 36 32 7d 20 54 68 69 73 20  * {F12662} This 
27470 63 61 6c 6c 20 64 69 73 61 62 6c 65 64 20 61 75  call disabled au
27480 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
27490 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
274a0 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  s. {END}.**.** T
274b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
274c0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
274d0 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  d is subject to 
274e0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d  change or.** rem
274f0 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72  oval in future r
27500 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
27510 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
27520 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
27530 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
27540 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ./*.****** EXPER
27550 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
27560 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
27570 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
27580 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20  *********.**.** 
27590 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
275a0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
275b0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
275c0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
275d0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
275e0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
275f0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
27600 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
27610 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
27620 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
27630 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
27640 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
27650 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
27660 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
27670 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
27680 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
27690 62 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  blizes, we will 
276a0 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
276b0 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
276c0 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
276d0 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
276e0 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
276f0 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
27700 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
27710 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
27720 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
27730 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
27740 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
27750 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
27760 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
27770 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
27780 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
27790 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
277a0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
277b0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
277c0 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
277d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
277e0 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
277f0 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20 6d 6f 64  le;../*.** A mod
27800 75 6c 65 20 69 73 20 61 20 63 6c 61 73 73 20 6f  ule is a class o
27810 66 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  f virtual tables
27820 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
27830 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20  s defined.** by 
27840 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
27850 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  he following str
27860 75 63 74 75 72 65 2e 20 20 54 68 69 73 20 73 74  ucture.  This st
27870 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
27880 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  .** mostly of me
27890 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
278a0 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  dule..*/.struct 
278b0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
278c0 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
278d0 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
278e0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
278f0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
27900 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
27910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
27920 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
27930 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
27940 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
27950 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
27960 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
27970 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
27980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
27990 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
279a0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
279b0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
279c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
279d0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
279e0 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
279f0 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
27a00 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
27a10 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
27a20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
27a30 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
27a40 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
27a50 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
27a60 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
27a70 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
27a80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
27a90 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
27aa0 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
27ab0 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
27ac0 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
27ad0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
27ae0 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
27af0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
27b00 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
27b10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
27b20 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
27b30 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
27b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
27b50 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
27b60 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
27b70 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
27b80 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
27b90 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
27ba0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
27bb0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
27bc0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
27bd0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
27be0 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
27bf0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
27c00 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
27c10 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
27c20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
27c30 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
27c40 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
27c50 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
27c60 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
27c70 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
27c80 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
27c90 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
27ca0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
27cb0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
27cc0 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
27cd0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
27ce0 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
27cf0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
27d00 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
27d10 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
27d20 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
27d30 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
27d40 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
27d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27d60 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
27d70 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
27d80 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
27d90 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
27da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27db0 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
27dc0 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
27dd0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
27de0 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
27df0 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
27e00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27e10 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
27e20 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
27e30 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
27e40 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
27e50 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
27e60 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
27e70 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 78 42  eply from the xB
27e80 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d 65 74 68  estIndex.** meth
27e90 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  od of an sqlite3
27ea0 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 66 69  _module.  The fi
27eb0 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
27ec0 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
27ed0 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
27ee0 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
27ef0 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
27f00 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
27f10 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
27f20 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
27f30 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54   fields..**.** T
27f40 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
27f50 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57   array records W
27f60 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
27f70 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 0a 2a  traints of the.*
27f80 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 20 20  * form:.**.**   
27f90 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 4f 50 20        column OP 
27fa0 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68 65 72 65  expr.**.** Where
27fb0 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
27fc0 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
27fd0 26 67 74 3b 3d 2e 20 20 0a 2a 2a 20 54 68 65 20  &gt;=.  .** The 
27fe0 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
27ff0 74 6f 72 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  tor is stored.**
28000 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
28010 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78  ].op.  The index
28020 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
28030 73 20 73 74 6f 72 65 64 20 69 6e 20 0a 2a 2a 20  s stored in .** 
28040 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
28050 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61  olumn.  aConstra
28060 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
28070 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
28080 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
28090 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
280a0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
280b0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
280c0 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
280d0 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
280e0 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a  it cannot..**.**
280f0 20 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61   The optimizer a
28100 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
28110 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
28120 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
28130 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
28140 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
28150 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
28160 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
28170 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
28180 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
28190 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
281a0 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
281b0 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
281c0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  ossible..** The 
281d0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
281e0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
281f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
28200 72 6d 73 20 69 6e 20 74 68 65 20 63 6f 72 72 65  rms in the corre
28210 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20  ct.** form that 
28220 72 65 66 65 72 20 74 6f 20 74 68 65 20 70 61 72  refer to the par
28230 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
28240 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
28250 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72  ied..**.** Infor
28260 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
28270 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
28280 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f   is stored in aO
28290 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63  rderBy[]..** Eac
282a0 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
282b0 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
282c0 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
282d0 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
282e0 2a 20 54 68 65 20 78 42 65 73 74 49 6e 64 65 78  * The xBestIndex
282f0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
28300 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
28310 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
28320 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
28330 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
28340 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
28350 72 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78  r.  If argvIndex
28360 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
28370 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
28380 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
28390 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
283a0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
283b0 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
283c0 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
283d0 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49  ntry in argv.  I
283e0 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
283f0 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
28400 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
28410 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
28420 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
28430 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
28440 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
28450 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
28460 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
28470 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ite..**.** The i
28480 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
28490 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
284a0 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
284b0 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e 0a 2a 2a  into xFilter..**
284c0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
284d0 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
284e0 69 64 78 50 74 72 20 69 66 20 6e 65 65 64 54 6f  idxPtr if needTo
284f0 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
28500 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 72  ue..**.** The or
28510 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
28520 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
28530 66 72 6f 6d 20 78 46 69 6c 74 65 72 20 77 69 6c  from xFilter wil
28540 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
28550 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
28560 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
28570 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
28580 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
28590 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
285a0 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
285b0 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74 69 6d 61  **.** The estima
285c0 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
285d0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
285e0 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
285f0 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
28600 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
28610 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
28620 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
28630 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
28640 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
28650 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
28660 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
28670 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
28680 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
28690 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
286a0 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
286b0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
286c0 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
286d0 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
286e0 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
286f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
28700 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
28710 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
28720 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
28730 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
28740 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
28750 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
28760 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
28770 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
28780 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
28790 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
287a0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
287b0 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
287c0 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
287d0 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
287e0 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
287f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
28800 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
28810 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
28820 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
28830 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
28840 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
28850 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
28860 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
28870 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
28880 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
28890 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
288a0 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
288b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
288c0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
288d0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
288e0 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
288f0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
28900 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
28910 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
28920 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
28930 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
28940 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
28950 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
28960 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
28970 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
28980 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
28990 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
289a0 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
289b0 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20 4f 75 74  use */..  /* Out
289c0 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
289d0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
289e0 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
289f0 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
28a00 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
28a10 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
28a20 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
28a30 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
28a40 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
28a50 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
28a60 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
28a70 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
28a80 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
28a90 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
28aa0 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
28ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28ac0 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
28ad0 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
28ae0 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
28af0 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
28b00 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
28b10 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
28b20 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
28b30 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
28b40 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
28b50 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
28b60 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
28b70 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
28b80 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
28b90 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
28ba0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
28bb0 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
28bc0 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
28bd0 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
28be0 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
28bf0 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
28c00 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
28c10 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
28c20 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
28c30 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
28c40 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
28c50 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
28c60 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
28c70 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
28c80 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
28c90 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
28ca0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
28cb0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
28cc0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
28cd0 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
28ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
28cf0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
28d00 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  CH 64../*.** Thi
28d10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65  s routine is use
28d20 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
28d30 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  new module name 
28d40 77 69 74 68 20 61 6e 20 53 51 4c 69 74 65 0a 2a  with an SQLite.*
28d50 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 4d  * connection.  M
28d60 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
28d70 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
28d80 65 66 6f 72 65 20 63 72 65 61 74 69 6e 67 20 6e  efore creating n
28d90 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  ew.** virtual ta
28da0 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d 6f 64 75  bles on the modu
28db0 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73  le, or before us
28dc0 69 6e 67 20 70 72 65 65 78 69 73 74 69 6e 67 20  ing preexisting 
28dd0 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65  virtual.** table
28de0 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  s of the module.
28df0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28e00 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
28e10 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28e20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
28e30 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
28e40 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
28e50 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
28e60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
28e70 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
28e80 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
28e90 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
28ea0 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f  3_module *,    /
28eb0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
28ec0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
28ed0 69 64 20 2a 20 20 20 20 20 20 20 20 20 20 20 20  id *            
28ee0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
28ef0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
28f00 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
28f10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 72  );../*.** This r
28f20 6f 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69  outine is identi
28f30 63 61 6c 20 74 6f 20 74 68 65 20 73 71 6c 69 74  cal to the sqlit
28f40 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
28f50 28 29 20 6d 65 74 68 6f 64 20 61 62 6f 76 65 2c  () method above,
28f60 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
28f70 69 74 20 61 6c 6c 6f 77 73 20 61 20 64 65 73 74  it allows a dest
28f80 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
28f90 74 6f 20 62 65 20 73 70 65 63 69 66 69 65 64 2e  to be specified.
28fa0 20 49 74 20 69 73 0a 2a 2a 20 65 76 65 6e 20 6d   It is.** even m
28fb0 6f 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  ore experimental
28fc0 20 74 68 61 6e 20 74 68 65 20 72 65 73 74 20 6f   than the rest o
28fd0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
28fe0 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a 69 6e 74  bles API..*/.int
28ff0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29000 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c  module_v2(.  sql
29010 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
29020 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
29030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
29040 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
29050 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
29060 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
29070 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
29080 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
29090 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
290a0 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a 20 4d 65  dule *,    /* Me
290b0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
290c0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
290d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
290e0 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
290f0 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
29100 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f  xConnect */.  vo
29110 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
29120 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75  id*)     /* Modu
29130 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  le destructor fu
29140 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a  nction */.);../*
29150 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64 75 6c 65  .** Every module
29160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29170 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
29180 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
29190 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 74 6f   structure.** to
291a0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
291b0 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20  icular instance 
291c0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
291d0 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69  Each subclass wi
291e0 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65  ll.** be tailore
291f0 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  d to the specifi
29200 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d  c needs of the m
29210 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
29220 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a 2a 20 70  tion.   The.** p
29230 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
29240 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
29250 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
29260 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 20 63  ields that are c
29270 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61 6c 6c 20  ommon.** to all 
29280 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
29290 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69  ations..**.** Vi
292a0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
292b0 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
292c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
292d0 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
292e0 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
292f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
29300 69 6e 74 66 28 29 20 74 6f 20 7a 45 72 72 4d 73  intf() to zErrMs
29310 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
29320 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
29330 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
29340 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
29350 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 73  d by a call to s
29360 71 6c 69 74 65 33 5f 66 72 65 65 28 29 0a 2a 2a  qlite3_free().**
29370 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
29380 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
29390 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
293a0 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
293b0 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
293c0 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
293d0 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
293e0 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
293f0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
29400 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
29410 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
29420 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
29430 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
29440 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a 2a 20 74  roed.  Note.** t
29450 68 61 74 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  hat sqlite3_mpri
29460 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
29470 33 5f 66 72 65 65 28 29 20 61 72 65 20 75 73 65  3_free() are use
29480 64 20 6f 6e 20 74 68 65 20 7a 45 72 72 4d 73 67  d on the zErrMsg
29490 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e 63 65 20   field.** since 
294a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 61  virtual tables a
294b0 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69 6d 70 6c  re commonly impl
294c0 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f 61 64 61  emented in loada
294d0 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 77  ble extensions w
294e0 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f 74 20 68  hich.** do not h
294f0 61 76 65 20 61 63 63 65 73 73 20 74 6f 20 73 71  ave access to sq
29500 6c 69 74 65 33 4d 50 72 69 6e 74 66 28 29 20 6f  lite3MPrintf() o
29510 72 20 73 71 6c 69 74 65 33 46 72 65 65 28 29 2e  r sqlite3Free().
29520 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
29530 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
29540 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
29550 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
29560 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
29570 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
29580 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
29590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
295a0 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e        /* Used in
295b0 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20 20 63 68  ternally */.  ch
295c0 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20  ar *zErrMsg;    
295d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
295e0 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66   Error message f
295f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  rom sqlite3_mpri
29600 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69  ntf() */.  /* Vi
29610 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
29620 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
29630 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
29640 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
29650 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76 65 72 79   */.};../* Every
29660 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
29670 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
29680 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 66 6f  bclass of the fo
29690 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
296a0 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72 69 62 65  e.** to describe
296b0 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
296c0 69 6e 74 20 69 6e 74 6f 20 74 68 65 20 76 69 72  int into the vir
296d0 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 61  tual table and a
296e0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
296f0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
29700 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
29710 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
29720 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
29730 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
29740 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
29750 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
29760 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
29770 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
29780 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
29790 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
297a0 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
297b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
297c0 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
297d0 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
297e0 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
297f0 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
29800 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
29810 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
29820 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
29830 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
29840 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
29850 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
29860 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
29870 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
29880 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
29890 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
298a0 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
298b0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
298c0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
298d0 0a 2a 2a 20 54 68 65 20 78 43 72 65 61 74 65 20  .** The xCreate 
298e0 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74  and xConnect met
298f0 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64 75 6c 65  hods of a module
29900 20 75 73 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69   use the followi
29910 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20 64 65 63  ng API.** to dec
29920 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
29930 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
29940 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
29950 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
29960 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
29970 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
29980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
29990 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
299a0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
299b0 61 72 20 2a 7a 43 72 65 61 74 65 54 61 62 6c 65  ar *zCreateTable
299c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72 74 75 61  );../*.** Virtua
299d0 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
299e0 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
299f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
29a00 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
29a10 20 75 73 69 6e 67 20 74 68 65 20 78 46 69 6e 64   using the xFind
29a20 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68 6f 64 2e  Function method.
29a30 20 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72    But global ver
29a40 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
29a50 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
29a60 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
29a70 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
29a80 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
29a90 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
29aa0 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
29ab0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
29ac0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
29ad0 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
29ae0 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
29af0 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
29b00 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
29b10 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
29b20 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
29b30 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
29b40 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
29b50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
29b60 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
29b70 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
29b80 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
29b90 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
29ba0 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
29bb0 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
29bc0 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
29bd0 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
29be0 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
29bf0 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
29c00 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  -holder function
29c10 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
29c20 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 76 69  rloaded.** by vi
29c30 72 74 75 61 6c 20 74 61 62 6c 65 73 2e 0a 2a 2a  rtual tables..**
29c40 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 73 68 6f  .** This API sho
29c50 75 6c 64 20 62 65 20 63 6f 6e 73 69 64 65 72 65  uld be considere
29c60 64 20 70 61 72 74 20 6f 66 20 74 68 65 20 76 69  d part of the vi
29c70 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
29c80 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69 63 68 20  rface,.** which 
29c90 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  is experimental 
29ca0 61 6e 64 20 73 75 62 6a 65 63 74 20 74 6f 20 63  and subject to c
29cb0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
29cc0 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
29cd0 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
29ce0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
29cf0 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
29d00 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
29d10 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
29d20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
29d30 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
29d40 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
29d50 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
29d60 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
29d70 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
29d80 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
29d90 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
29da0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
29db0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
29dc0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
29dd0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
29de0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
29df0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
29e00 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
29e10 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
29e20 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
29e30 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
29e40 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
29e50 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
29e60 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
29e70 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
29e80 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
29e90 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
29ea0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
29eb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45  ent..**.****** E
29ec0 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
29ed0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
29ee0 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
29ef0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f  *************.*/
29f00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29f10 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
29f20 20 4f 70 65 6e 20 42 4c 4f 42 20 7b 46 31 37 38   Open BLOB {F178
29f30 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  00}.**.** An ins
29f40 74 61 6e 63 65 20 6f 66 20 74 68 65 20 66 6f 6c  tance of the fol
29f50 6c 6f 77 69 6e 67 20 6f 70 61 71 75 65 20 73 74  lowing opaque st
29f60 72 75 63 74 75 72 65 20 69 73 20 75 73 65 64 20  ructure is used 
29f70 74 6f 20 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  to .** represent
29f80 20 61 6e 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 2e   an blob-handle.
29f90 20 20 41 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 20    A blob-handle 
29fa0 69 73 20 63 72 65 61 74 65 64 20 62 79 0a 2a 2a  is created by.**
29fb0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
29fc0 70 65 6e 28 29 5d 20 61 6e 64 20 64 65 73 74 72  pen()] and destr
29fd0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
29fe0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
29ff0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2a000 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
2a010 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
2a020 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
2a030 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
2a040 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
2a050 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
2a060 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 6c 6f 62  ions of the blob
2a070 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2a080 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
2a090 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a0a0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
2a0b0 65 0a 2a 2a 20 62 6c 6f 62 20 69 6e 20 62 79 74  e.** blob in byt
2a0c0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
2a0d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
2a0e0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
2a0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a100 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
2a110 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
2a120 4f 20 7b 46 31 37 38 31 30 7d 0a 2a 2a 0a 2a 2a  O {F17810}.**.**
2a130 20 7b 46 31 37 38 31 31 7d 20 54 68 69 73 20 69   {F17811} This i
2a140 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
2a150 61 20 68 61 6e 64 6c 65 20 74 6f 20 74 68 65 20  a handle to the 
2a160 62 6c 6f 62 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  blob located.** 
2a170 69 6e 20 72 6f 77 20 69 52 6f 77 2c 2c 20 63 6f  in row iRow,, co
2a180 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
2a190 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
2a1a0 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
2a1b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 20  n other words,  
2a1c0 74 68 65 20 73 61 6d 65 20 62 6c 6f 62 20 74 68  the same blob th
2a1d0 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
2a1e0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
2a1f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
2a200 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
2a210 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
2a220 20 72 6f 77 69 64 20 3d 20 69 52 6f 77 3b 0a 2a   rowid = iRow;.*
2a230 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a  * </pre> {END}.*
2a240 2a 0a 2a 2a 20 7b 46 31 37 38 31 32 7d 20 49 66  *.** {F17812} If
2a250 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
2a260 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
2a270 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70  , the blob is op
2a280 65 6e 65 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61  ened for .** rea
2a290 64 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65  d and write acce
2a2a0 73 73 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72  ss. If it is zer
2a2b0 6f 2c 20 74 68 65 20 62 6c 6f 62 20 69 73 20 6f  o, the blob is o
2a2c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 0a  pened for read .
2a2d0 2a 2a 20 61 63 63 65 73 73 2e 20 7b 45 4e 44 7d  ** access. {END}
2a2e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 31 33 7d 20  .**.** {F17813} 
2a2f0 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
2a300 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
2a310 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
2a320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2a330 62 20 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d  b | blob handle]
2a340 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a   is written to *
2a350 70 70 42 6c 6f 62 2e 20 0a 2a 2a 20 7b 46 31 37  ppBlob. .** {F17
2a360 38 31 34 7d 20 4f 74 68 65 72 77 69 73 65 20 61  814} Otherwise a
2a370 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  n error code is 
2a380 72 65 74 75 72 6e 65 64 20 61 6e 64 20 0a 2a 2a  returned and .**
2a390 20 61 6e 79 20 76 61 6c 75 65 20 77 72 69 74 74   any value writt
2a3a0 65 6e 20 74 6f 20 2a 70 70 42 6c 6f 62 20 73 68  en to *ppBlob sh
2a3b0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
2a3c0 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 0a   by the caller..
2a3d0 2a 2a 20 7b 46 31 37 38 31 35 7d 20 54 68 69 73  ** {F17815} This
2a3e0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
2a3f0 68 65 20 64 61 74 61 62 61 73 65 2d 68 61 6e 64  he database-hand
2a400 6c 65 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  le error code an
2a410 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
2a420 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
2a430 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2a440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
2a450 6d 73 67 28 29 5d 2e 0a 2a 2a 20 3c 74 6f 64 6f  msg()]..** <todo
2a460 3e 57 65 20 73 68 6f 75 6c 64 20 67 6f 20 74 68  >We should go th
2a470 72 6f 75 67 68 20 61 6e 64 20 6d 61 72 6b 20 61  rough and mark a
2a480 6c 6c 20 69 6e 74 65 72 66 61 63 65 73 20 74 68  ll interfaces th
2a490 61 74 20 62 65 68 61 76 65 20 74 68 69 73 0a 2a  at behave this.*
2a4a0 2a 20 77 61 79 20 77 69 74 68 20 61 20 73 69 6d  * way with a sim
2a4b0 69 6c 61 72 20 73 74 61 74 65 6d 65 6e 74 3c 2f  ilar statement</
2a4c0 74 6f 64 6f 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  todo>.*/.int sql
2a4d0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a  ite3_blob_open(.
2a4e0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f    sqlite3*,.  co
2a4f0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20  nst char *zDb,. 
2a500 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61   const char *zTa
2a510 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  ble,.  const cha
2a520 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71  r *zColumn,.  sq
2a530 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77  lite3_int64 iRow
2a540 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20  ,.  int flags,. 
2a550 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a   sqlite3_blob **
2a560 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ppBlob.);../*.**
2a570 20 43 41 50 49 33 52 45 46 3a 20 20 43 6c 6f 73   CAPI3REF:  Clos
2a580 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20  e A BLOB Handle 
2a590 7b 46 31 37 38 33 30 7d 0a 2a 2a 0a 2a 2a 20 43  {F17830}.**.** C
2a5a0 6c 6f 73 65 20 61 6e 20 6f 70 65 6e 20 5b 73 71  lose an open [sq
2a5b0 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f  lite3_blob | blo
2a5c0 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  b handle]..**.**
2a5d0 20 7b 46 31 37 38 33 31 7d 20 43 6c 6f 73 69 6e   {F17831} Closin
2a5e0 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63  g a BLOB shall c
2a5f0 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74  ause the current
2a600 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
2a610 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65  commit.** if the
2a620 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
2a630 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e  BLOBs, no pendin
2a640 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  g prepared state
2a650 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ments, and the.*
2a660 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2a670 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75 74 6f  ction is in auto
2a680 63 6f 6d 6d 69 74 20 6d 6f 64 65 2e 0a 2a 2a 20  commit mode..** 
2a690 7b 46 31 37 38 33 32 7d 20 49 66 20 61 6e 79 20  {F17832} If any 
2a6a0 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
2a6b0 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
2a6c0 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
2a6d0 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
2a6e0 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
2a6f0 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
2a700 69 6c 6c 20 66 69 74 2e 20 7b 45 4e 44 7d 0a 2a  ill fit. {END}.*
2a710 2a 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  * Closing the BL
2a720 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
2a730 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
2a740 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
2a750 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
2a760 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
2a770 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
2a780 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
2a790 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
2a7a0 73 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 37 38  s closed.  {F178
2a7b0 33 33 7d 20 41 6e 79 20 65 72 72 6f 72 73 20 74  33} Any errors t
2a7c0 68 61 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67  hat occur during
2a7d0 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20  .** closing are 
2a7e0 72 65 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f  reported as a no
2a7f0 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61  n-zero return va
2a800 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38  lue..**.** {F178
2a810 33 39 7d 20 54 68 65 20 42 4c 4f 42 20 69 73 20  39} The BLOB is 
2a820 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
2a830 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
2a840 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2a850 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
2a860 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
2a870 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
2a880 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a890 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
2a8a0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
2a8b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 52  .** CAPI3REF:  R
2a8c0 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
2a8d0 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b  f An Open BLOB {
2a8e0 46 31 37 38 30 35 7d 0a 2a 2a 0a 2a 2a 20 7b 46  F17805}.**.** {F
2a8f0 31 36 38 30 36 7d 20 52 65 74 75 72 6e 20 74 68  16806} Return th
2a900 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
2a910 6f 66 20 74 68 65 20 62 6c 6f 62 20 61 63 63 65  of the blob acce
2a920 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 6f  ssible via the o
2a930 70 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  pen .** [sqlite3
2a940 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e  _blob | blob-han
2a950 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73 20 61  dle] passed as a
2a960 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2f 0a 69  n argument..*/.i
2a970 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
2a980 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
2a990 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
2a9a0 50 49 33 52 45 46 3a 20 20 52 65 61 64 20 44 61  PI3REF:  Read Da
2a9b0 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
2a9c0 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 46 31  ncrementally {F1
2a9d0 37 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7850}.**.** This
2a9e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2a9f0 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66  d to read data f
2aa00 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a 2a 20  rom an open .** 
2aa10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20  [sqlite3_blob | 
2aa20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69 6e 74  blob-handle] int
2aa30 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70 70 6c  o a caller suppl
2aa40 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a 20 7b  ied buffer..** {
2aa50 46 31 37 38 35 31 7d 20 6e 20 62 79 74 65 73 20  F17851} n bytes 
2aa60 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
2aa70 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 0a 2a  ed into buffer.*
2aa80 2a 20 7a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  * z from the ope
2aa90 6e 20 62 6c 6f 62 2c 20 73 74 61 72 74 69 6e 67  n blob, starting
2aaa0 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
2aab0 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 35  et..**.** {F1785
2aac0 32 7d 20 49 66 20 6f 66 66 73 65 74 20 69 4f 66  2} If offset iOf
2aad0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
2aae0 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n n bytes from t
2aaf0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 62 6c  he end of the bl
2ab00 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ob, .** [SQLITE_
2ab10 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
2ab20 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
2ab30 73 20 72 65 61 64 2e 20 20 7b 46 31 37 38 35 33  s read.  {F17853
2ab40 7d 20 49 66 20 6e 20 69 73 0a 2a 2a 20 6c 65 73  } If n is.** les
2ab50 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c  s than zero [SQL
2ab60 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
2ab70 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
2ab80 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 0a 2a  ta is read..**.*
2ab90 2a 20 7b 46 31 37 38 35 34 7d 20 4f 6e 20 73 75  * {F17854} On su
2aba0 63 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b  ccess, SQLITE_OK
2abb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74   is returned. Ot
2abc0 68 65 72 77 69 73 65 2c 20 61 6e 20 0a 2a 2a 20  herwise, an .** 
2abd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
2abe0 53 51 4c 69 74 65 20 65 72 72 6f 72 20 63 6f 64  SQLite error cod
2abf0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  e] or an.** [SQL
2ac00 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
2ac10 20 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20   extended error 
2ac20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2ac30 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2ac40 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69  3_blob_read(sqli
2ac50 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64  te3_blob *, void
2ac60 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20   *z, int n, int 
2ac70 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a  iOffset);../*.**
2ac80 20 43 41 50 49 33 52 45 46 3a 20 20 57 72 69 74   CAPI3REF:  Writ
2ac90 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42 4c  e Data Into A BL
2aca0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
2acb0 20 7b 46 31 37 38 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F17870}.**.** 
2acc0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
2acd0 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64   used to write d
2ace0 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e  ata into an open
2acf0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c   .** [sqlite3_bl
2ad00 6f 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65  ob | blob-handle
2ad10 5d 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75  ] from a user su
2ad20 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a  pplied buffer..*
2ad30 2a 20 7b 46 31 37 38 37 31 7d 20 6e 20 62 79 74  * {F17871} n byt
2ad40 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
2ad50 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62  opied from the b
2ad60 75 66 66 65 72 0a 2a 2a 20 70 6f 69 6e 74 65 64  uffer.** pointed
2ad70 20 74 6f 20 62 79 20 7a 20 69 6e 74 6f 20 74 68   to by z into th
2ad80 65 20 6f 70 65 6e 20 62 6c 6f 62 2c 20 73 74 61  e open blob, sta
2ad90 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
2ada0 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  iOffset..**.** {
2adb0 46 31 37 38 37 32 7d 20 49 66 20 74 68 65 20 5b  F17872} If the [
2adc0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62  sqlite3_blob | b
2add0 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73  lob-handle] pass
2ade0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2adf0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  argument.** was 
2ae00 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 20 77  not opened for w
2ae10 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
2ae20 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
2ae30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
2ae40 6e 28 29 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72  n()].*** was zer
2ae50 6f 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  o), this functio
2ae60 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
2ae70 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
2ae80 2a 2a 20 7b 46 31 37 38 37 33 7d 20 54 68 69 73  ** {F17873} This
2ae90 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e   function may on
2aea0 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f  ly modify the co
2aeb0 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 62 6c  ntents of the bl
2aec0 6f 62 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74  ob; it is.** not
2aed0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63   possible to inc
2aee0 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f  rease the size o
2aef0 66 20 61 20 62 6c 6f 62 20 75 73 69 6e 67 20 74  f a blob using t
2af00 68 69 73 20 41 50 49 2e 0a 2a 2a 20 7b 46 31 37  his API..** {F17
2af10 38 37 34 7d 20 49 66 20 6f 66 66 73 65 74 20 69  874} If offset i
2af20 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
2af30 68 61 6e 20 6e 20 62 79 74 65 73 20 66 72 6f 6d  han n bytes from
2af40 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
2af50 62 6c 6f 62 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54  blob, .** [SQLIT
2af60 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
2af70 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
2af80 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 7b 46   is written.  {F
2af90 31 37 38 37 35 7d 20 49 66 20 6e 20 69 73 0a 2a  17875} If n is.*
2afa0 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
2afb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2afc0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
2afd0 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
2afe0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 38 37  en..**.** {F1787
2aff0 36 7d 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  6} On success, S
2b000 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
2b010 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  rned. Otherwise,
2b020 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
2b030 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65  ERROR | SQLite e
2b040 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
2b050 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
2b060 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
2b070 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
2b080 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
2b090 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
2b0a0 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
2b0b0 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
2b0c0 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
2b0d0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
2b0e0 43 41 50 49 33 52 45 46 3a 20 20 56 69 72 74 75  CAPI3REF:  Virtu
2b0f0 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f  al File System O
2b100 62 6a 65 63 74 73 20 7b 46 31 31 32 30 30 7d 0a  bjects {F11200}.
2b110 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
2b120 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
2b130 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
2b140 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
2b150 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
2b160 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
2b170 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
2b180 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
2b190 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69 6c 64  tem.  Most build
2b1a0 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
2b1b0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
2b1c0 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
2b1d0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
2b1e0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
2b1f0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
2b200 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
2b210 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
2b220 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
2b230 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
2b240 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
2b250 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
2b260 2a 2a 0a 2a 2a 20 7b 46 31 31 32 30 31 7d 20 54  **.** {F11201} T
2b270 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  he sqlite3_vfs_f
2b280 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20  ind() interface 
2b290 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2b2a0 72 20 74 6f 20 0a 2a 2a 20 61 20 56 46 53 20 67  r to .** a VFS g
2b2b0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2b2c0 7b 46 31 31 32 30 32 7d 20 4e 61 6d 65 73 20 61  {F11202} Names a
2b2d0 72 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76  re case sensitiv
2b2e0 65 2e 0a 2a 2a 20 7b 46 31 31 32 30 33 7d 20 4e  e..** {F11203} N
2b2f0 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65  ames are zero-te
2b300 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2b310 74 72 69 6e 67 73 2e 0a 2a 2a 20 7b 46 31 31 32  trings..** {F112
2b320 30 34 7d 20 49 66 20 74 68 65 72 65 20 69 73 20  04} If there is 
2b330 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c  no match, a NULL
2b340 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72  .** pointer is r
2b350 65 74 75 72 6e 65 64 2e 20 7b 46 31 31 32 30 35  eturned. {F11205
2b360 7d 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73  } If zVfsName is
2b370 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
2b380 65 66 61 75 6c 74 20 0a 2a 2a 20 56 46 53 20 69  efault .** VFS i
2b390 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 45 4e 44  s returned. {END
2b3a0 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 32 31 30 7d  }.**.** {F11210}
2b3b0 20 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72   New VFSes are r
2b3c0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73  egistered with s
2b3d0 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
2b3e0 74 65 72 28 29 2e 0a 2a 2a 20 7b 46 31 31 32 31  ter()..** {F1121
2b3f0 31 7d 20 45 61 63 68 20 6e 65 77 20 56 46 53 20  1} Each new VFS 
2b400 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
2b410 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
2b420 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
2b430 73 65 74 2e 0a 2a 2a 20 7b 46 31 31 32 31 32 7d  set..** {F11212}
2b440 20 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61   The same VFS ca
2b450 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
2b460 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
2b470 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a  ithout injury..*
2b480 2a 20 7b 46 31 31 32 31 33 7d 20 54 6f 20 6d 61  * {F11213} To ma
2b490 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56  ke an existing V
2b4a0 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61  FS into the defa
2b4b0 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65  ult VFS, registe
2b4c0 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69  r it again.** wi
2b4d0 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  th the makeDflt 
2b4e0 66 6c 61 67 20 73 65 74 2e 20 7b 55 31 31 32 31  flag set. {U1121
2b4f0 34 7d 20 49 66 20 74 77 6f 20 64 69 66 66 65 72  4} If two differ
2b500 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74  ent VFSes with t
2b510 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20  he.** same name 
2b520 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20  are registered, 
2b530 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b540 75 6e 64 65 66 69 6e 65 64 2e 20 20 7b 55 31 31  undefined.  {U11
2b550 32 31 35 7d 20 49 66 20 61 0a 2a 2a 20 56 46 53  215} If a.** VFS
2b560 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
2b570 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20  ith a name that 
2b580 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
2b590 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74  pty string,.** t
2b5a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2b5b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2b5c0 2a 20 0a 2a 2a 20 7b 46 31 31 32 32 30 7d 20 55  * .** {F11220} U
2b5d0 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20  nregister a VFS 
2b5e0 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33  with the sqlite3
2b5f0 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
2b600 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  ) interface..** 
2b610 7b 46 31 31 32 32 31 7d 20 49 66 20 74 68 65 20  {F11221} If the 
2b620 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
2b630 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f  nregistered, ano
2b640 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73  ther VFS is chos
2b650 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66  en as.** the def
2b660 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63  ault.  The choic
2b670 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46  e for the new VF
2b680 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a  S is arbitrary..
2b690 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  */.sqlite3_vfs *
2b6a0 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
2b6b0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66  (const char *zVf
2b6c0 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69  sName);.int sqli
2b6d0 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
2b6e0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
2b6f0 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e  nt makeDflt);.in
2b700 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  t sqlite3_vfs_un
2b710 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
2b720 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _vfs*);../*.** C
2b730 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65 73  API3REF: Mutexes
2b740 20 7b 46 31 37 30 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17000}.**.** 
2b750 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
2b760 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
2b770 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a  nes for thread.*
2b780 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  * synchronizatio
2b790 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65 79 20  n.  Though they 
2b7a0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
2b7b0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
2b7c0 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
2b7d0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2b7e0 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
2b7f0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
2b800 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2b810 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
2b820 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
2b830 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
2b840 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2b850 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66 20 74  tations .** of t
2b860 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69  hese mutex routi
2b870 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72  nes.  An appropr
2b880 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iate implementat
2b890 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74  ion.** is select
2b8a0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
2b8b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
2b8c0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
2b8d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2b8e0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
2b8f0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
2b900 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  core:.**.** <ul>
2b910 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
2b920 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c  E_MUTEX_OS2.** <
2b930 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
2b940 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c  EX_PTHREAD.** <l
2b950 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
2b960 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_W32.** <li>   
2b970 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
2b980 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  P.** </ul>.**.**
2b990 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45   The SQLITE_MUTE
2b9a0 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
2b9b0 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
2b9c0 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a 20 74  f routines .** t
2b9d0 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
2b9e0 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
2b9f0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
2ba00 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73 69 6e  use in .** a sin
2ba10 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
2ba20 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53  lication.  The S
2ba30 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
2ba40 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
2ba50 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
2ba60 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
2ba70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
2ba80 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
2ba90 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f 73 2f  e for use on os/
2baa0 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77 69 6e  2, unix, and win
2bab0 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  dows..** .** If 
2bac0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2bad0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
2bae0 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
2baf0 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
2bb00 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
2bb10 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
2bb20 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
2bb30 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
2bb40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2bb50 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
2bb60 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 20 54   the library.  T
2bb70 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e 74 65  he.** mutex inte
2bb80 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 64  rface routines d
2bb90 65 66 69 6e 65 64 20 68 65 72 65 20 62 65 63 6f  efined here beco
2bba0 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a 20 72  me external.** r
2bbb0 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74 68 65  eferences in the
2bbc0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
2bbd0 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c 65 6d  for which implem
2bbe0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  entations.** mus
2bbf0 74 20 62 65 20 70 72 6f 76 69 64 65 64 20 62 79  t be provided by
2bc00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2bc10 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69 74 79  .  This facility
2bc20 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20 61 70   allows an.** ap
2bc30 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 6c  plication that l
2bc40 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
2bc50 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65 20 69  ite to provide i
2bc60 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a 2a 20  ts own mutex.** 
2bc70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2bc80 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
2bc90 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 69   modify the SQLi
2bca0 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  te core..**.** {
2bcb0 46 31 37 30 31 31 7d 20 54 68 65 20 73 71 6c 69  F17011} The sqli
2bcc0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
2bcd0 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61  ) routine alloca
2bce0 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74  tes a new.** mut
2bcf0 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ex and returns a
2bd00 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
2bd10 7b 46 31 37 30 31 32 7d 20 49 66 20 69 74 20 72  {F17012} If it r
2bd20 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74  eturns NULL.** t
2bd30 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61  hat means that a
2bd40 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74   mutex could not
2bd50 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 7b   be allocated. {
2bd60 46 31 37 30 31 33 7d 20 53 51 4c 69 74 65 0a 2a  F17013} SQLite.*
2bd70 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74  * will unwind it
2bd80 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74 75  s stack and retu
2bd90 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b 46 31  rn an error. {F1
2bda0 37 30 31 34 7d 20 54 68 65 20 61 72 67 75 6d 65  7014} The argume
2bdb0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
2bdc0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
2bdd0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
2bde0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
2bdf0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2be00 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
2be10 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
2be20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
2be30 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
2be40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
2be50 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
2be60 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
2be70 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
2be80 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
2be90 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
2bea0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
2beb0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
2bec0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
2bed0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
2bee0 55 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  U.** </ul> {END}
2bef0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 35 7d 20  .**.** {F17015} 
2bf00 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f  The first two co
2bf10 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20 73 71  nstants cause sq
2bf20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
2bf30 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a  c() to create.**
2bf40 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54   a new mutex.  T
2bf50 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
2bf60 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
2bf70 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
2bf80 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
2bf90 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
2bfa0 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
2bfb0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
2bfc0 73 20 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  s used. {END}.**
2bfd0 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65   The mutex imple
2bfe0 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e  mentation does n
2bff0 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20  ot need to make 
2c000 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  a distinction.**
2c010 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
2c020 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
2c030 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
2c040 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73  _FAST if it does
2c050 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e  .** not want to.
2c060 20 20 7b 46 31 37 30 31 36 7d 20 42 75 74 20 53    {F17016} But S
2c070 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
2c080 72 65 71 75 65 73 74 20 61 20 72 65 63 75 72 73  request a recurs
2c090 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20  ive mutex in.** 
2c0a0 63 61 73 65 73 20 77 68 65 72 65 20 69 74 20 72  cases where it r
2c0b0 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e  eally needs one.
2c0c0 20 20 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73    {END} If a fas
2c0d0 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76  ter non-recursiv
2c0e0 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  e mutex.** imple
2c0f0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61  mentation is ava
2c100 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f  ilable on the ho
2c110 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65  st platform, the
2c120 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d   mutex subsystem
2c130 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e  .** might return
2c140 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e   such a mutex in
2c150 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c   response to SQL
2c160 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a  ITE_MUTEX_FAST..
2c170 2a 2a 0a 2a 2a 20 7b 46 31 37 30 31 37 7d 20 54  **.** {F17017} T
2c180 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64  he other allowed
2c190 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73   parameters to s
2c1a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
2c1b0 6f 63 28 29 20 65 61 63 68 20 72 65 74 75 72 6e  oc() each return
2c1c0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2c1d0 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
2c1e0 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e  sting mutex. {EN
2c1f0 44 7d 20 20 46 6f 75 72 20 73 74 61 74 69 63 20  D}  Four static 
2c200 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75  mutexes are.** u
2c210 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65  sed by the curre
2c220 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  nt version of SQ
2c230 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65  Lite.  Future ve
2c240 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2c250 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69  .** may add addi
2c260 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
2c270 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d  texes.  Static m
2c280 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69  utexes are for i
2c290 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
2c2a0 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20  y SQLite only.  
2c2b0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
2c2c0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74  t use SQLite mut
2c2d0 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75  exes should.** u
2c2e0 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61  se only the dyna
2c2f0 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75  mic mutexes retu
2c300 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d  rned by SQLITE_M
2c310 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20  UTEX_FAST or.** 
2c320 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
2c330 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46  URSIVE..**.** {F
2c340 31 37 30 31 38 7d 20 4e 6f 74 65 20 74 68 61 74  17018} Note that
2c350 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
2c360 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
2c370 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
2c380 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
2c390 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
2c3a0 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
2c3b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
2c3c0 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
2c3d0 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
2c3e0 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
2c3f0 79 20 63 61 6c 6c 2e 20 20 7b 46 31 37 30 33 34  y call.  {F17034
2c400 7d 20 42 75 74 20 66 6f 72 20 74 68 65 20 73 74  } But for the st
2c410 61 74 69 63 20 0a 2a 2a 20 6d 75 74 65 78 20 74  atic .** mutex t
2c420 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d  ypes, the same m
2c430 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64  utex is returned
2c440 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74   on every call t
2c450 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73  hat has.** the s
2c460 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e  ame type number.
2c470 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
2c480 37 30 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65  7019} The sqlite
2c490 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72  3_mutex_free() r
2c4a0 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74  outine deallocat
2c4b0 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a  es a previously.
2c4c0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e  ** allocated dyn
2c4d0 61 6d 69 63 20 6d 75 74 65 78 2e 20 7b 46 31 37  amic mutex. {F17
2c4e0 30 32 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63  020} SQLite is c
2c4f0 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
2c500 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
2c510 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
2c520 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b   it allocates. {
2c530 55 31 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61  U17021} The dyna
2c540 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74  mic mutexes must
2c550 20 6e 6f 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75   not be in .** u
2c560 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  se when they are
2c570 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 55   deallocated. {U
2c580 31 37 30 32 32 7d 20 41 74 74 65 6d 70 74 69 6e  17022} Attemptin
2c590 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  g to deallocate 
2c5a0 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65  a static.** mute
2c5b0 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  x results in und
2c5c0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2c5d0 20 7b 46 31 37 30 32 33 7d 20 53 51 4c 69 74 65   {F17023} SQLite
2c5e0 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74   never deallocat
2c5f0 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d  es.** a static m
2c600 75 74 65 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  utex. {END}.**.*
2c610 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
2c620 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20  tex_enter() and 
2c630 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
2c640 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74  y() routines att
2c650 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72  empt.** to enter
2c660 20 61 20 6d 75 74 65 78 2e 20 7b 46 31 37 30 32   a mutex. {F1702
2c670 34 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  4} If another th
2c680 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
2c690 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
2c6a0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
2c6b0 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
2c6c0 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
2c6d0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
2c6e0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
2c6f0 49 54 45 5f 42 55 53 59 2e 20 7b 46 31 37 30 32  ITE_BUSY. {F1702
2c700 35 7d 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  5}  The sqlite3_
2c710 6d 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65  mutex_try() inte
2c720 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 53 51  rface returns SQ
2c730 4c 49 54 45 5f 4f 4b 0a 2a 2a 20 75 70 6f 6e 20  LITE_OK.** upon 
2c740 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
2c750 2e 20 20 7b 46 31 37 30 32 36 7d 20 4d 75 74 65  .  {F17026} Mute
2c760 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  xes created usin
2c770 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  g.** SQLITE_MUTE
2c780 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20  X_RECURSIVE can 
2c790 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69  be entered multi
2c7a0 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65  ple times by the
2c7b0 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a   same thread..**
2c7c0 20 7b 46 31 37 30 32 37 7d 20 49 6e 20 73 75 63   {F17027} In suc
2c7d0 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
2c7e0 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
2c7f0 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
2c800 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
2c810 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
2c820 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
2c830 2e 20 20 7b 55 31 37 30 32 38 7d 20 49 66 20 74  .  {U17028} If t
2c840 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
2c850 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
2c860 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
2c870 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
2c880 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
2c890 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2c8a0 65 64 2e 0a 2a 2a 20 7b 46 31 37 30 32 39 7d 20  ed..** {F17029} 
2c8b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
2c8c0 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
2c8d0 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
2c8e0 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
2c8f0 65 78 65 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  exes. {END}.**.*
2c900 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28  * Some systems (
2c910 65 78 3a 20 77 69 6e 64 6f 77 73 39 35 29 20 64  ex: windows95) d
2c920 6f 20 6e 6f 74 20 74 68 65 20 6f 70 65 72 61 74  o not the operat
2c930 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  ion implemented 
2c940 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  by.** sqlite3_mu
2c950 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74  tex_try().  On t
2c960 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71  hose systems, sq
2c970 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
2c980 29 20 77 69 6c 6c 0a 2a 2a 20 61 6c 77 61 79 73  ) will.** always
2c990 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42   return SQLITE_B
2c9a0 55 53 59 2e 20 20 7b 46 31 37 30 33 30 7d 20 54  USY.  {F17030} T
2c9b0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
2c9c0 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a  nly ever uses.**
2c9d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
2c9e0 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d  ry() as an optim
2c9f0 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20  ization so this 
2ca00 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65  is acceptable be
2ca10 68 61 76 69 6f 72 2e 20 7b 45 4e 44 7d 0a 2a 2a  havior. {END}.**
2ca20 0a 2a 2a 20 7b 46 31 37 30 33 31 7d 20 54 68 65  .** {F17031} The
2ca30 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
2ca40 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65  eave() routine e
2ca50 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68 61  xits a mutex tha
2ca60 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  t was.** previou
2ca70 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  sly entered by t
2ca80 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20  he same thread. 
2ca90 20 7b 55 31 37 30 33 32 7d 20 54 68 65 20 62 65   {U17032} The be
2caa0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2cab0 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75  efined if the mu
2cac0 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65  tex is not curre
2cad0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  ntly entered by 
2cae0 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74  the.** calling t
2caf0 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20  hread or is not 
2cb00 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
2cb10 74 65 64 2e 20 20 7b 46 31 37 30 33 33 7d 20 53  ted.  {F17033} S
2cb20 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
2cb30 76 65 72 20 64 6f 20 65 69 74 68 65 72 2e 20 7b  ver do either. {
2cb40 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  END}.**.** See a
2cb50 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  lso: [sqlite3_mu
2cb60 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20  tex_held()] and 
2cb70 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e  [sqlite3_mutex_n
2cb80 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71  otheld()]..*/.sq
2cb90 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
2cba0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
2cbb0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69  (int);.void sqli
2cbc0 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73  te3_mutex_free(s
2cbd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
2cbe0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
2cbf0 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33  ex_enter(sqlite3
2cc00 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
2cc10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
2cc20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
2cc30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
2cc40 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65  tex_leave(sqlite
2cc50 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a  3_mutex*);../*.*
2cc60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
2cc70 78 20 56 65 72 69 66 63 61 74 69 6f 6e 20 52 6f  x Verifcation Ro
2cc80 75 74 69 6e 65 73 20 7b 46 31 37 30 38 30 7d 0a  utines {F17080}.
2cc90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2cca0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
2ccb0 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
2ccc0 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
2ccd0 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
2cce0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
2ccf0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
2cd00 65 6d 65 6e 74 73 2e 20 7b 46 31 37 30 38 31 7d  ements. {F17081}
2cd10 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
2cd20 0a 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74  .** never uses t
2cd30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78  hese routines ex
2cd40 63 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61  cept inside an a
2cd50 73 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c  ssert() and appl
2cd60 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ications.** are 
2cd70 61 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f  advised to follo
2cd80 77 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68  w the lead of th
2cd90 65 20 63 6f 72 65 2e 20 20 7b 46 31 37 30 38 32  e core.  {F17082
2cda0 7d 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a  } The core only.
2cdb0 2a 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c  ** provides impl
2cdc0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
2cdd0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  these routines w
2cde0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
2cdf0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53  ed.** with the S
2ce00 51 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67  QLITE_DEBUG flag
2ce10 2e 20 20 7b 55 31 37 30 38 37 7d 20 45 78 74 65  .  {U17087} Exte
2ce20 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65  rnal mutex imple
2ce30 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
2ce40 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20  e only required 
2ce50 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65  to provide these
2ce60 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c   routines if SQL
2ce70 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20  ITE_DEBUG is.** 
2ce80 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e  defined and if N
2ce90 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66  DEBUG is not def
2cea0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ined..**.** {F17
2ceb0 30 38 33 7d 20 54 68 65 73 65 20 72 6f 75 74 69  083} These routi
2cec0 6e 65 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  nes should retur
2ced0 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 6d 75  n true if the mu
2cee0 74 65 78 20 69 6e 20 74 68 65 69 72 20 61 72 67  tex in their arg
2cef0 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64  ument.** is held
2cf00 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65   or not held, re
2cf10 73 70 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74  spectively, by t
2cf20 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
2cf30 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b  d. {END}.**.** {
2cf40 58 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c  X17084} The impl
2cf50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f  ementation is no
2cf60 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  t required to pr
2cf70 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20  ovided versions 
2cf80 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74  of these.** rout
2cf90 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c  ines that actual
2cfa0 6c 79 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74  ly work..** If t
2cfb0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2cfc0 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  n does not provi
2cfd0 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65  de working.** ve
2cfe0 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20  rsions of these 
2cff0 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f  routines, it sho
2d000 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f  uld at least pro
2d010 76 69 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68  vide stubs.** th
2d020 61 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  at always return
2d030 20 74 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e   true so that on
2d040 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73  e does not get s
2d050 70 75 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72  purious.** asser
2d060 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 20 7b  tion failures. {
2d070 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 30  END}.**.** {F170
2d080 38 35 7d 20 49 66 20 74 68 65 20 61 72 67 75 6d  85} If the argum
2d090 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ent to sqlite3_m
2d0a0 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61  utex_held() is a
2d0b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2d0c0 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  en.** the routin
2d0d0 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
2d0e0 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69 73 20 73  1.  {END} This s
2d0f0 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
2d100 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
2d110 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
2d120 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
2d130 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
2d140 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
2d150 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
2d160 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
2d170 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
2d180 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
2d190 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
2d1a0 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
2d1b0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
2d1c0 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
2d1d0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
2d1e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
2d1f0 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
2d200 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
2d210 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
2d220 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
2d230 6f 20 64 6f 2e 20 20 7b 46 31 37 30 38 36 7d 20  o do.  {F17086} 
2d240 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
2d250 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20  x_notheld() .** 
2d260 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
2d270 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77   also return 1 w
2d280 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c  hen given a NULL
2d290 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74   pointer..*/.int
2d2a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
2d2b0 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
2d2c0 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
2d2d0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73  _mutex_notheld(s
2d2e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
2d2f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d300 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b 46 31   Mutex Types {F1
2d310 37 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  7001}.**.** {F17
2d320 30 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  002} The [sqlite
2d330 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
2d340 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73   interface takes
2d350 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2d360 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f  nt.** which is o
2d370 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
2d380 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 20 7b  ger constants. {
2d390 45 4e 44 7d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  END}.*/.#define 
2d3a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
2d3b0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a  T             0.
2d3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
2d3d0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20  UTEX_RECURSIVE  
2d3e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2d3f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
2d400 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a  TIC_MASTER    2.
2d410 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
2d420 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20  UTEX_STATIC_MEM 
2d430 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69        3  /* sqli
2d440 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a  te3_malloc() */.
2d450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
2d460 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
2d470 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
2d480 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2d490 72 79 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ry() */.#define 
2d4a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
2d4b0 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20  TIC_PRNG      5 
2d4c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64   /* sqlite3_rand
2d4d0 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  om() */.#define 
2d4e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
2d4f0 54 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20  TIC_LRU       6 
2d500 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73   /* lru page lis
2d510 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t */../*.** CAPI
2d520 33 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20  3REF: Low-Level 
2d530 43 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62  Control Of Datab
2d540 61 73 65 20 46 69 6c 65 73 20 7b 46 31 31 33 30  ase Files {F1130
2d550 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 31  0}.**.** {F11301
2d560 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  } The [sqlite3_f
2d570 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
2d580 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2d590 20 64 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20   direct call to 
2d5a0 74 68 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74  the.** xFileCont
2d5b0 72 6f 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74  rol method for t
2d5c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
2d5d0 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
2d5e0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
2d5f0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
2d600 61 74 61 62 61 73 65 20 69 64 65 6e 74 69 66 69  atabase identifi
2d610 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
2d620 20 61 72 67 75 6d 65 6e 74 2e 20 7b 46 31 31 33   argument. {F113
2d630 30 32 7d 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20  02} The.** name 
2d640 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2d650 69 73 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  is the name assi
2d660 67 6e 65 64 20 74 6f 20 74 68 65 20 64 61 74 61  gned to the data
2d670 62 61 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c  base by the.** <
2d680 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74  a href="lang_att
2d690 61 63 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48  ach.html">ATTACH
2d6a0 3c 2f 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  </a> SQL command
2d6b0 20 74 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65   that opened the
2d6c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 7b 46  .** database. {F
2d6d0 31 31 33 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f  11303} To contro
2d6e0 6c 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  l the main datab
2d6f0 61 73 65 20 66 69 6c 65 2c 20 75 73 65 20 74 68  ase file, use th
2d700 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a  e name "main".**
2d710 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
2d720 65 72 2e 20 7b 46 31 31 33 30 34 7d 20 54 68 65  er. {F11304} The
2d730 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2d740 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
2d750 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
2d760 61 72 65 20 70 61 73 73 65 64 20 64 69 72 65 63  are passed direc
2d770 74 6c 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74  tly through to t
2d780 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
2d790 69 72 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f  ird parameters o
2d7a0 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f  f.** the xFileCo
2d7b0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b  ntrol method.  {
2d7c0 46 31 31 33 30 35 7d 20 54 68 65 20 72 65 74 75  F11305} The retu
2d7d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
2d7e0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20  xFileControl.** 
2d7f0 6d 65 74 68 6f 64 20 62 65 63 6f 6d 65 73 20 74  method becomes t
2d800 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2d810 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
2d820 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 36 7d 20  .**.** {F11306} 
2d830 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
2d840 72 61 6d 65 74 65 72 20 28 7a 44 62 4e 61 6d 65  rameter (zDbName
2d850 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  ) does not match
2d860 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79   the name of any
2d870 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61 73  .** open databas
2d880 65 20 66 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c  e file, then SQL
2d890 49 54 45 5f 45 52 52 4f 52 20 69 73 20 72 65 74  ITE_ERROR is ret
2d8a0 75 72 6e 65 64 2e 20 7b 46 31 31 33 30 37 7d 20  urned. {F11307} 
2d8b0 54 68 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f  This error.** co
2d8c0 64 65 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62  de is not rememb
2d8d0 65 72 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f  ered and will no
2d8e0 74 20 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79  t be recalled by
2d8f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2d900 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  e()].** or [sqli
2d910 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b  te3_errmsg()]. {
2d920 55 31 31 33 30 38 7d 20 54 68 65 20 75 6e 64 65  U11308} The unde
2d930 72 6c 79 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74  rlying xFileCont
2d940 72 6f 6c 20 6d 65 74 68 6f 64 20 6d 69 67 68 74  rol method might
2d950 0a 2a 2a 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  .** also return 
2d960 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b  SQLITE_ERROR.  {
2d970 55 31 31 33 30 39 7d 20 54 68 65 72 65 20 69 73  U11309} There is
2d980 20 6e 6f 20 77 61 79 20 74 6f 20 64 69 73 74 69   no way to disti
2d990 6e 67 75 69 73 68 20 62 65 74 77 65 65 6e 0a 2a  nguish between.*
2d9a0 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a  * an incorrect z
2d9b0 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e 20 53 51  DbName and an SQ
2d9c0 4c 49 54 45 5f 45 52 52 4f 52 20 72 65 74 75 72  LITE_ERROR retur
2d9d0 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e 64 65 72  n from the under
2d9e0 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f  lying.** xFileCo
2d9f0 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45  ntrol method. {E
2da00 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ND}.**.** See al
2da10 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  so: [SQLITE_FCNT
2da20 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a  L_LOCKSTATE].*/.
2da30 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  int sqlite3_file
2da40 5f 63 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33  _control(sqlite3
2da50 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2da60 44 62 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20  DbName, int op, 
2da70 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55  void*);../*.** U
2da80 6e 64 6f 20 74 68 65 20 68 61 63 6b 20 74 68 61  ndo the hack tha
2da90 74 20 63 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74  t converts float
2daa0 69 6e 67 20 70 6f 69 6e 74 20 74 79 70 65 73 20  ing point types 
2dab0 74 6f 20 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a  to integer for.*
2dac0 2a 20 62 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63  * builds on proc
2dad0 65 73 73 6f 72 73 20 77 69 74 68 6f 75 74 20 66  essors without f
2dae0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75  loating point su
2daf0 70 70 6f 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  pport..*/.#ifdef
2db00 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2db10 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e  ATING_POINT.# un
2db20 64 65 66 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69  def double.#endi
2db30 66 0a 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  f..#ifdef __cplu
2db40 73 70 6c 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20  splus.}  /* End 
2db50 6f 66 20 74 68 65 20 27 65 78 74 65 72 6e 20 22  of the 'extern "
2db60 43 22 27 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e  C"' block */.#en
2db70 64 69 66 0a 23 65 6e 64 69 66 0a                 dif.#endif.