System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 9c18fa7b03b0769f5ffa7520769c99610bf0dbb1:


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 33 2e 68  ) $Id: sqlite3.h
05e0: 2c 76 20 31 2e 33 33 20 32 30 30 37 2f 31 32 2f  ,v 1.33 2007/12/
05f0: 30 34 20 31 36 3a 31 31 3a 31 33 20 72 6d 73 69  04 16:11:13 rmsi
0600: 6d 70 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23  mpson Exp $.*/.#
0610: 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f  ifndef _SQLITE3_
0620: 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49  H_.#define _SQLI
0630: 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20  TE3_H_.#include 
0640: 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f  <stdarg.h>     /
0650: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65  * Needed for the
0660: 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76   definition of v
0670: 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  a_list */../*.**
0680: 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61   Make sure we ca
0690: 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66  n call this stuf
06a0: 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23  f from C++..*/.#
06b0: 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75  ifdef __cplusplu
06c0: 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  s.extern "C" {.#
06d0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64  endif.../*.** Ad
06e0: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  d the ability to
06f0: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72   override 'exter
0700: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  n'.*/.#ifndef SQ
0710: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65  LITE_EXTERN.# de
0720: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45  fine SQLITE_EXTE
0730: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66  RN extern.#endif
0740: 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72  ../*.** Make sur
0750: 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20  e these symbols 
0760: 77 68 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65  where not define
0770: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
0780: 75 73 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c  us header.** fil
0790: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
07a0: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e  ITE_VERSION.# un
07b0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07c0: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  ON.#endif.#ifdef
07d0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
07e0: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53  NUMBER.# undef S
07f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0800: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  MBER.#endif../*.
0810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
0820: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72  pile-Time Librar
0830: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
0840: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 65 72 73  s.**.** The vers
0850: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
0860: 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6e  e library is con
0870: 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 73 71  tained in the sq
0880: 6c 69 74 65 33 2e 68 0a 2a 2a 20 68 65 61 64 65  lite3.h.** heade
0890: 72 20 66 69 6c 65 20 69 6e 20 61 20 23 64 65 66  r file in a #def
08a0: 69 6e 65 20 6e 61 6d 65 64 20 53 51 4c 49 54 45  ine named SQLITE
08b0: 5f 56 45 52 53 49 4f 4e 2e 20 20 54 68 65 20 53  _VERSION.  The S
08c0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 2a 2a  QLITE_VERSION.**
08d0: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
08e0: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
08f0: 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tant..**.** The 
0900: 66 6f 72 6d 61 74 20 6f 66 20 74 68 65 20 76 65  format of the ve
0910: 72 73 69 6f 6e 20 73 74 72 69 6e 67 20 69 73 20  rsion string is 
0920: 22 58 2e 59 2e 5a 22 2c 20 77 68 65 72 65 0a 2a  "X.Y.Z", where.*
0930: 2a 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72  * X is the major
0940: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 2c   version number,
0950: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0960: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0970: 6e 64 20 5a 0a 2a 2a 20 69 73 20 74 68 65 20 72  nd Z.** is the r
0980: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 20 20  elease number.  
0990: 54 68 65 20 58 2e 59 2e 5a 20 6d 69 67 68 74 20  The X.Y.Z might 
09a0: 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 22  be followed by "
09b0: 61 6c 70 68 61 22 20 6f 72 20 22 62 65 74 61 22  alpha" or "beta"
09c0: 2e 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  ..** For example
09d0: 20 22 33 2e 31 2e 31 62 65 74 61 22 2e 0a 2a 2a   "3.1.1beta"..**
09e0: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20  .** The X value 
09f0: 69 73 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53  is always 3 in S
0a00: 51 4c 69 74 65 2e 20 20 54 68 65 20 58 20 76 61  QLite.  The X va
0a10: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  lue only changes
0a20: 20 77 68 65 6e 0a 2a 2a 20 62 61 63 6b 77 61 72   when.** backwar
0a30: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
0a40: 20 69 73 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77   is broken and w
0a50: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65  e intend to neve
0a60: 72 20 62 72 65 61 6b 0a 2a 2a 20 62 61 63 6b 77  r break.** backw
0a70: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
0a80: 74 79 2e 20 20 54 68 65 20 59 20 76 61 6c 75 65  ty.  The Y value
0a90: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68   only changes wh
0aa0: 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20  en.** there are 
0ab0: 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e  major feature en
0ac0: 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20  hancements that 
0ad0: 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d  are forwards com
0ae0: 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e  patible.** but n
0af0: 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ot backwards com
0b00: 70 61 74 69 62 6c 65 2e 20 20 54 68 65 20 5a 20  patible.  The Z 
0b10: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 6d 65  value is increme
0b20: 6e 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63  nted with.** eac
0b30: 68 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65  h release but re
0b40: 73 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77  sets back to 0 w
0b50: 68 65 6e 20 59 20 69 73 20 69 6e 63 72 65 6d 65  hen Y is increme
0b60: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nted..**.** The 
0b70: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0b80: 55 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65  UMBER is an inte
0b90: 67 65 72 20 77 69 74 68 20 74 68 65 20 76 61 6c  ger with the val
0ba0: 75 65 20 0a 2a 2a 20 28 58 2a 31 30 30 30 30 30  ue .** (X*100000
0bb0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 2e  0 + Y*1000 + Z).
0bc0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 66 6f   For example, fo
0bd0: 72 20 76 65 72 73 69 6f 6e 20 22 33 2e 31 2e 31  r version "3.1.1
0be0: 62 65 74 61 22 2c 20 0a 2a 2a 20 53 51 4c 49 54  beta", .** SQLIT
0bf0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c00: 20 69 73 20 73 65 74 20 74 6f 20 33 30 30 31 30   is set to 30010
0c10: 30 31 2e 20 54 6f 20 64 65 74 65 63 74 20 69 66  01. To detect if
0c20: 20 74 68 65 79 20 61 72 65 20 75 73 69 6e 67 20   they are using 
0c30: 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 31 2e  .** version 3.1.
0c40: 31 20 6f 72 20 67 72 65 61 74 65 72 20 61 74 20  1 or greater at 
0c50: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2c 20 70 72  compile time, pr
0c60: 6f 67 72 61 6d 73 20 6d 61 79 20 75 73 65 20 74  ograms may use t
0c70: 68 65 20 74 65 73 74 20 0a 2a 2a 20 28 53 51 4c  he test .** (SQL
0c80: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0c90: 45 52 3e 3d 33 30 30 31 30 30 31 29 2e 0a 2a 2a  ER>=3001001)..**
0ca0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
0cb0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0cc0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0cd0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
0ce0: 62 65 72 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ber()]..*/.#defi
0cf0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
0d00: 4e 20 20 20 20 20 20 20 20 20 22 33 2e 35 2e 33  N         "3.5.3
0d10: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
0d20: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0d30: 33 30 30 35 30 30 33 0a 0a 2f 2a 0a 2a 2a 20 43  3005003../*.** C
0d40: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
0d50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0d60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0d70: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
0d80: 65 74 75 72 6e 20 76 61 6c 75 65 73 20 65 71 75  eturn values equ
0d90: 69 76 61 6c 65 6e 74 20 74 6f 20 74 68 65 20 68  ivalent to the h
0da0: 65 61 64 65 72 20 63 6f 6e 73 74 61 6e 74 73 0a  eader constants.
0db0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
0dc0: 4f 4e 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ON] and [SQLITE_
0dd0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
0de0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74    The values ret
0df0: 75 72 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  urned.** by this
0e00: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
0e10: 20 6f 6e 6c 79 20 62 65 20 64 69 66 66 65 72 65   only be differe
0e20: 6e 74 20 66 72 6f 6d 20 74 68 65 20 68 65 61 64  nt from the head
0e30: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 69 66 20  er values.** if 
0e40: 79 6f 75 20 63 6f 6d 70 69 6c 65 20 79 6f 75 72  you compile your
0e50: 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 61   program using a
0e60: 6e 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64  n sqlite3.h head
0e70: 65 72 20 66 72 6f 6d 20 61 0a 2a 2a 20 64 69 66  er from a.** dif
0e80: 66 65 72 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f  ferent version o
0e90: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 74 68  f SQLite that th
0ea0: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
0eb0: 20 6c 69 62 72 61 72 79 20 79 6f 75 0a 2a 2a 20   library you.** 
0ec0: 6c 69 6e 6b 20 61 67 61 69 6e 73 74 2e 0a 2a 2a  link against..**
0ed0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
0ee0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
0ef0: 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69   constant contai
0f00: 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  ns the text of t
0f10: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  he.** [SQLITE_VE
0f20: 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 20 20  RSION] string.  
0f30: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
0f40: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
0f50: 6e 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  n returns.** a p
0f60: 6f 69 6e 65 72 20 74 6f 20 74 68 65 20 73 71 6c  oiner to the sql
0f70: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0f80: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
0f90: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   The function.**
0fa0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
0fb0: 20 44 4c 4c 20 75 73 65 72 73 20 77 68 6f 20 63   DLL users who c
0fc0: 61 6e 20 6f 6e 6c 79 20 61 63 63 65 73 73 20 66  an only access f
0fd0: 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 6e 6f 74  unctions and not
0fe0: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  .** constants wi
0ff0: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2f  thin the DLL..*/
1000: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
1010: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
1020: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
1030: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1040: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
1050: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1060: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1070: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1080: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1090: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
10a0: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
10b0: 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  e.**.** This rou
10c0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 54 52 55  tine returns TRU
10d0: 45 20 28 6e 6f 6e 7a 65 72 6f 29 20 69 66 20 53  E (nonzero) if S
10e0: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
10f0: 65 64 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 6f  ed with.** all o
1100: 66 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e  f its mutexes en
1110: 61 62 6c 65 64 20 61 6e 64 20 69 73 20 74 68 75  abled and is thu
1120: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 49  s threadsafe.  I
1130: 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 7a 65 72  t returns.** zer
1140: 6f 20 69 66 20 74 68 65 20 70 61 72 74 69 63 75  o if the particu
1150: 6c 61 72 20 62 75 69 6c 64 20 69 73 20 66 6f 72  lar build is for
1160: 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
1170: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 6f 6e   operation.** on
1180: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 61 6c 6c 79  ly..**.** Really
1190: 20 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e   all this routin
11a0: 65 20 64 6f 65 73 20 69 73 20 72 65 74 75 72 6e  e does is return
11b0: 20 74 72 75 65 20 69 66 20 53 51 4c 69 74 65 20   true if SQLite 
11c0: 77 61 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  was compiled.** 
11d0: 77 69 74 68 20 74 68 65 20 2d 44 53 51 4c 49 54  with the -DSQLIT
11e0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f  E_THREADSAFE=1 o
11f0: 70 74 69 6f 6e 20 61 6e 64 20 66 61 6c 73 65 20  ption and false 
1200: 69 66 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  if.** compiled w
1210: 69 74 68 20 2d 44 53 51 4c 49 54 45 5f 54 48 52  ith -DSQLITE_THR
1220: 45 41 44 53 41 46 45 3d 30 2e 20 20 49 66 20 53  EADSAFE=0.  If S
1230: 51 4c 69 74 65 20 75 73 65 73 20 61 6e 0a 2a 2a  QLite uses an.**
1240: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1250: 69 6e 65 64 20 6d 75 74 65 78 20 73 75 62 73 79  ined mutex subsy
1260: 73 74 65 6d 2c 20 6d 61 6c 6c 6f 63 20 73 75 62  stem, malloc sub
1270: 73 79 73 74 65 6d 2c 20 63 6f 6c 6c 61 74 69 6e  system, collatin
1280: 67 0a 2a 2a 20 73 65 71 75 65 6e 63 65 2c 20 56  g.** sequence, V
1290: 46 53 2c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  FS, SQL function
12a0: 2c 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  , progress callb
12b0: 61 63 6b 2c 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  ack, commit hook
12c0: 2c 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 2c 20  ,.** extension, 
12d0: 6f 72 20 6f 74 68 65 72 20 61 63 63 65 73 73 6f  or other accesso
12e0: 72 69 65 73 20 61 6e 64 20 74 68 65 73 65 20 61  ries and these a
12f0: 64 64 2d 6f 6e 73 20 61 72 65 20 6e 6f 74 0a 2a  dd-ons are not.*
1300: 2a 20 74 68 72 65 61 64 73 61 66 65 2c 20 74 68  * threadsafe, th
1310: 65 6e 20 63 6c 65 61 72 6c 79 20 74 68 65 20 63  en clearly the c
1320: 6f 6d 62 69 6e 61 74 69 6f 6e 20 77 69 6c 6c 20  ombination will 
1330: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
1340: 65 0a 2a 2a 20 65 69 74 68 65 72 2e 20 20 48 65  e.** either.  He
1350: 6e 63 65 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  nce, this routin
1360: 65 20 6e 65 76 65 72 20 72 65 70 6f 72 74 73 20  e never reports 
1370: 74 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79  that the library
1380: 0a 2a 2a 20 69 73 20 67 75 61 72 61 6e 74 65 65  .** is guarantee
1390: 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
13a0: 66 65 2c 20 6f 6e 6c 79 20 77 68 65 6e 20 69 74  fe, only when it
13b0: 20 69 73 20 67 75 61 72 61 6e 74 65 65 64 20 6e   is guaranteed n
13c0: 6f 74 0a 2a 2a 20 74 6f 20 62 65 2e 0a 2a 2a 0a  ot.** to be..**.
13d0: 2a 2a 20 54 68 69 73 20 69 73 20 61 6e 20 65 78  ** This is an ex
13e0: 70 65 72 69 6d 65 6e 74 61 6c 20 41 50 49 20 61  perimental API a
13f0: 6e 64 20 6d 61 79 20 67 6f 20 61 77 61 79 20 6f  nd may go away o
1400: 72 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  r change in futu
1410: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 73 2e 0a  re.** releases..
1420: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1430: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
1440: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1450: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1460: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 0a  ction Handle.**.
1470: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
1480: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
1490: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 70  represented by p
14a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
14b0: 74 61 6e 63 65 20 6f 66 20 74 68 65 0a 2a 2a 20  tance of the.** 
14c0: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
14d0: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
14e0: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
14f0: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1500: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1510: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1520: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1530: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1540: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1550: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1560: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1570: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1580: 63 74 6f 72 73 0a 2a 2a 20 61 6e 64 20 5b 73 71  ctors.** and [sq
1590: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
15a0: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
15b0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
15c0: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
15d0: 65 73 0a 2a 2a 20 28 73 75 63 68 20 61 73 20 5b  es.** (such as [
15e0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15f0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
1600: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
1610: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1620: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1630: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
1640: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
1650: 6d 65 74 68 6f 64 73 20 6f 6e 20 74 68 69 73 0a  methods on this.
1660: 2a 2a 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  ** object..*/.ty
1670: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1680: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 0a  ite3 sqlite3;...
1690: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16a0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
16b0: 79 70 65 73 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  ypes.**.** Some 
16c0: 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20 6e 6f 74  compilers do not
16d0: 20 73 75 70 70 6f 72 74 20 74 68 65 20 22 6c 6f   support the "lo
16e0: 6e 67 20 6c 6f 6e 67 22 20 64 61 74 61 74 79 70  ng long" datatyp
16f0: 65 2e 20 20 53 6f 20 77 65 20 68 61 76 65 0a 2a  e.  So we have.*
1700: 2a 20 74 6f 20 64 6f 20 63 6f 6d 70 69 6c 65 72  * to do compiler
1710: 2d 73 70 65 63 69 66 69 63 20 74 79 70 65 64 65  -specific typede
1720: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
1730: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
1740: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
1750: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  * Many SQLite in
1760: 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1770: 73 20 72 65 71 75 69 72 65 20 61 20 36 34 2d 62  s require a 64-b
1780: 69 74 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  it integer argum
1790: 65 6e 74 73 2e 0a 2a 2a 20 54 68 6f 73 65 20 69  ents..** Those i
17a0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 64 65  nterfaces are de
17b0: 63 6c 61 72 65 64 20 75 73 69 6e 67 20 74 68 69  clared using thi
17c0: 73 20 74 79 70 65 64 65 66 2e 0a 2a 2f 0a 23 69  s typedef..*/.#i
17d0: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
17e0: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
17f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1800: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1810: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1820: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1830: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1840: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1850: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
1860: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
1870: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
1880: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
1890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
18a0: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
18b0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
18c0: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
18d0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
18e0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
18f0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
1900: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
1910: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
1920: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
1930: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
1940: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
1950: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
1960: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
1970: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
1980: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
1990: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
19a0: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
19b0: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
19c0: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
19d0: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 0a 2a 2f 0a  oating-point.*/.
19e0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
19f0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
1a00: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
1a10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
1a20: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
1a30: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
1a40: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
1a50: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  ction.**.** Call
1a60: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 77   this function w
1a70: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
1a80: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
1a90: 74 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  t was previously
1aa0: 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
1ab0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
1ac0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1ad0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
1ae0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1af0: 5d 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 73  ] and the corres
1b00: 70 6f 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  ponding database
1b10: 20 77 69 6c 6c 20 62 79 0a 2a 2a 20 63 6c 6f 73   will by.** clos
1b20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6c 6c 20 53 51  ed..**.** All SQ
1b30: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 72 65  L statements pre
1b40: 70 61 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  pared using [sql
1b50: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b60: 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1b70: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1b80: 5d 20 6d 75 73 74 20 62 65 20 64 65 73 74 72 6f  ] must be destro
1b90: 79 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  yed using [sqlit
1ba0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
1bb0: 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 72 6f  * before this ro
1bc0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2e  utine is called.
1bd0: 20 4f 74 68 65 72 77 69 73 65 2c 20 53 51 4c 49   Otherwise, SQLI
1be0: 54 45 5f 42 55 53 59 20 69 73 20 72 65 74 75 72  TE_BUSY is retur
1bf0: 6e 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ned and the.** d
1c00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c10: 6f 6e 20 72 65 6d 61 69 6e 73 20 6f 70 65 6e 2e  on remains open.
1c20: 0a 2a 2a 0a 2a 2a 20 50 61 73 73 69 6e 67 20 74  .**.** Passing t
1c30: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 20 64 61  his routine a da
1c40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c50: 6e 20 74 68 61 74 20 68 61 73 20 61 6c 72 65 61  n that has alrea
1c60: 64 79 20 62 65 65 6e 0a 2a 2a 20 63 6c 6f 73 65  dy been.** close
1c70: 64 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  d results in und
1c80: 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1c90: 20 20 49 66 20 6f 74 68 65 72 20 69 6e 74 65 72    If other inter
1ca0: 66 61 63 65 73 20 74 68 61 74 0a 2a 2a 20 72 65  faces that.** re
1cb0: 66 65 72 65 6e 63 65 20 74 68 65 20 73 61 6d 65  ference the same
1cc0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cd0: 74 69 6f 6e 20 61 72 65 20 70 65 6e 64 69 6e 67  tion are pending
1ce0: 20 28 65 69 74 68 65 72 20 69 6e 20 74 68 65 0a   (either in the.
1cf0: 2a 2a 20 73 61 6d 65 20 74 68 72 65 61 64 20 6f  ** same thread o
1d00: 72 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  r in different t
1d10: 68 72 65 61 64 73 29 20 77 68 65 6e 20 74 68 69  hreads) when thi
1d20: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
1d30: 6c 65 64 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  led,.** then the
1d40: 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1d50: 65 66 69 6e 65 64 20 61 6e 64 20 69 73 20 61 6c  efined and is al
1d60: 6d 6f 73 74 20 63 65 72 74 61 69 6e 6c 79 20 75  most certainly u
1d70: 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69  ndesirable..*/.i
1d80: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
1d90: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
1da0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
1db0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1dc0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
1dd0: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
1de0: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
1df0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
1e00: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
1e10: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
1e20: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
1e30: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
1e40: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
1e50: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
1e60: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
1e70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
1e80: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
1e90: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
1ea0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1eb0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
1ec0: 20 64 6f 20 61 20 6f 6e 65 2d 74 69 6d 65 20 65   do a one-time e
1ed0: 76 61 6c 75 61 74 61 74 69 6f 6e 20 6f 66 20 7a  valuatation of z
1ee0: 65 72 6f 0a 2a 2a 20 6f 72 20 6d 6f 72 65 20 53  ero.** or more S
1ef0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
1f00: 55 54 46 2d 38 20 74 65 78 74 20 6f 66 20 74 68  UTF-8 text of th
1f10: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1f20: 20 74 6f 0a 2a 2a 20 62 65 20 65 76 61 6c 75 74   to.** be evalut
1f30: 65 64 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  ed is passed in 
1f40: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1f50: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 73 74  rameter.  The st
1f60: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72 65 20  atements.** are 
1f70: 70 72 65 70 61 72 65 64 20 6f 6e 65 20 62 79 20  prepared one by 
1f80: 6f 6e 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  one using [sqlit
1f90: 65 33 5f 70 72 65 70 61 72 65 28 29 5d 2c 20 65  e3_prepare()], e
1fa0: 76 61 6c 75 61 74 65 64 0a 2a 2a 20 75 73 69 6e  valuated.** usin
1fb0: 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1fc0: 29 5d 2c 20 74 68 65 6e 20 64 65 73 74 72 6f 79  )], then destroy
1fd0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1fe0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1ff0: 2a 0a 2a 2a 20 49 66 20 6f 6e 65 20 6f 72 20 6d  *.** If one or m
2000: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
2010: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 71 75  tatements are qu
2020: 65 72 69 65 73 2c 20 74 68 65 6e 0a 2a 2a 20 74  eries, then.** t
2030: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
2040: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
2050: 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  y the 3rd parame
2060: 74 65 72 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65  ter is.** invoke
2070: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2080: 72 6f 77 20 6f 66 20 74 68 65 20 71 75 65 72 79  row of the query
2090: 20 72 65 73 75 6c 74 2e 20 20 54 68 69 73 20 63   result.  This c
20a0: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 73 68 6f 75 6c  allback.** shoul
20b0: 64 20 6e 6f 72 6d 61 6c 6c 79 20 72 65 74 75 72  d normally retur
20c0: 6e 20 30 2e 20 20 49 66 20 74 68 65 20 63 61 6c  n 0.  If the cal
20d0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
20e0: 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 76 61 6c 75  non-zero.** valu
20f0: 65 20 74 68 65 6e 20 74 68 65 20 71 75 65 72 79  e then the query
2100: 20 69 73 20 61 62 6f 72 74 65 64 2c 20 61 6c 6c   is aborted, all
2110: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
2120: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 72  statements.** ar
2130: 65 20 73 6b 69 70 70 65 64 20 61 6e 64 20 74 68  e skipped and th
2140: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2150: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
2160: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 42  s the [SQLITE_AB
2170: 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ORT]..**.** The 
2180: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2190: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
21a0: 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
21b0: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 0a  pointer that is.
21c0: 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
21d0: 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
21e0: 6b 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 69 74  k function as it
21f0: 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2200: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 32 6e 64  r..**.** The 2nd
2210: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2220: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2230: 69 6f 6e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ion is the numbe
2240: 72 20 6f 66 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  r of.** columns 
2250: 69 6e 20 74 68 65 20 71 75 65 72 79 20 72 65 73  in the query res
2260: 75 6c 74 2e 20 20 54 68 65 20 33 72 64 20 70 61  ult.  The 3rd pa
2270: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
2280: 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 61 6e  allback.** is an
2290: 20 61 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67   array of string
22a0: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76 61  s holding the va
22b0: 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f  lues for each co
22c0: 6c 75 6d 6e 0a 2a 2a 20 61 73 20 65 78 74 72 61  lumn.** as extra
22d0: 63 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  cted using [sqli
22e0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
22f0: 29 5d 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  )]..** The 4th p
2300: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2310: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
2320: 72 72 61 79 20 6f 66 20 73 74 72 69 6e 67 73 0a  rray of strings.
2330: 2a 2a 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e  ** obtained usin
2340: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  g [sqlite3_colum
2350: 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 68 6f  n_name()] and ho
2360: 6c 64 69 6e 67 0a 2a 2a 20 74 68 65 20 6e 61 6d  lding.** the nam
2370: 65 73 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d  es of each colum
2380: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  n..**.** The cal
2390: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
23a0: 61 79 20 62 65 20 4e 55 4c 4c 2c 20 65 76 65 6e  ay be NULL, even
23b0: 20 66 6f 72 20 71 75 65 72 69 65 73 2e 20 20 41   for queries.  A
23c0: 20 4e 55 4c 4c 0a 2a 2a 20 63 61 6c 6c 62 61 63   NULL.** callbac
23d0: 6b 20 69 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f  k is not an erro
23e0: 72 2e 20 20 49 74 20 6a 75 73 74 20 6d 65 61 6e  r.  It just mean
23f0: 73 20 74 68 61 74 20 6e 6f 20 63 61 6c 6c 62 61  s that no callba
2400: 63 6b 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 69 6e  ck.** will be in
2410: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  voked..**.** If 
2420: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2430: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
2440: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20   evaluating the 
2450: 53 51 4c 20 28 62 75 74 0a 2a 2a 20 6e 6f 74 20  SQL (but.** not 
2460: 77 68 69 6c 65 20 65 78 65 63 75 74 69 6e 67 20  while executing 
2470: 74 68 65 20 63 61 6c 6c 62 61 63 6b 29 20 74 68  the callback) th
2480: 65 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  en an appropriat
2490: 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
24a0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
24b0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
24c0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
24d0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 0a 2a  _malloc()] and.*
24e0: 2a 20 2a 65 72 72 6d 73 67 20 69 73 20 6d 61 64  * *errmsg is mad
24f0: 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2500: 61 74 20 6d 65 73 73 61 67 65 2e 20 20 54 68 65  at message.  The
2510: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2520: 6e 0a 2a 2a 20 69 73 20 72 65 73 70 6f 6e 73 69  n.** is responsi
2530: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
2540: 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67  the memory using
2550: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2560: 5d 2e 0a 2a 2a 20 49 66 20 65 72 72 6d 73 67 3d  ]..** If errmsg=
2570: 3d 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 65  =NULL, then no e
2580: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20  rror message is 
2590: 65 76 65 72 20 77 72 69 74 74 65 6e 2e 0a 2a 2a  ever written..**
25a0: 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
25b0: 61 6c 75 65 20 69 73 20 69 73 20 53 51 4c 49 54  alue is is SQLIT
25c0: 45 5f 4f 4b 20 69 66 20 74 68 65 72 65 20 61 72  E_OK if there ar
25d0: 65 20 6e 6f 20 65 72 72 6f 72 73 20 61 6e 64 0a  e no errors and.
25e0: 2a 2a 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 53  ** some other [S
25f0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 74 75 72  QLITE_OK | retur
2600: 6e 20 63 6f 64 65 5d 20 69 66 20 74 68 65 72 65  n code] if there
2610: 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 20 0a   is an error.  .
2620: 2a 2a 20 54 68 65 20 70 61 72 74 69 63 75 6c 61  ** The particula
2630: 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 64  r return value d
2640: 65 70 65 6e 64 73 20 6f 6e 20 74 68 65 20 74 79  epends on the ty
2650: 70 65 20 6f 66 20 65 72 72 6f 72 2e 20 0a 2a 2a  pe of error. .**
2660: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2670: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
2680: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2690: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26a0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
26b0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
26c0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
26d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26e0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
26f0: 20 62 65 20 65 76 61 6c 75 74 65 64 20 2a 2f 0a   be evaluted */.
2700: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
2710: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2720: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
2730: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
2740: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
2750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2760: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2770: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
2780: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
2790: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
27a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27c0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
27d0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
27e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
27f0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
2800: 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2810: 4f 4b 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  OK.**.** Many SQ
2820: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
2830: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
2840: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
2850: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
2860: 2a 2a 20 61 62 6f 76 65 20 69 6e 20 6f 72 64 65  ** above in orde
2870: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73  r to indicates s
2880: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
2890: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 73  e..**.** The res
28a0: 75 6c 74 20 63 6f 64 65 73 20 61 62 6f 76 65 20  ult codes above 
28b0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6f 6e 65  are the only one
28c0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
28d0: 4c 69 74 65 20 69 6e 20 69 74 73 0a 2a 2a 20 64  Lite in its.** d
28e0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
28f0: 74 69 6f 6e 2e 20 20 48 6f 77 65 76 65 72 2c 20  tion.  However, 
2900: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  the [sqlite3_ext
2910: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
2920: 65 73 28 29 5d 0a 2a 2a 20 41 50 49 20 63 61 6e  es()].** API can
2930: 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 20   be used to set 
2940: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2950: 63 74 6f 69 6e 20 74 6f 20 72 65 74 75 72 6e 20  ctoin to return 
2960: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a  more detailed.**
2970: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 2e 0a 2a   result codes..*
2980: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2990: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
29a0: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
29b0: 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2a 0a 2a 2f  ult codes].**.*/
29c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29d0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
29e0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
29f0: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
2a00: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
2a10: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
2a20: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
2a30: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
2a40: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
2a50: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
2a60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
2a70: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 4e  NAL     2   /* N
2a80: 4f 54 20 55 53 45 44 2e 20 49 6e 74 65 72 6e 61  OT USED. Interna
2a90: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
2aa0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
2ab0: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
2ac0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
2ad0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
2ae0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
2af0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
2b00: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
2b10: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
2b20: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
2b30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2b40: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
2b50: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
2b60: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
2b70: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
2b80: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
2b90: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
2ba0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
2bb0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
2bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
2bd0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
2be0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
2bf0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
2c00: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
2c10: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
2c20: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
2c30: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
2c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c50: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
2c60: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
2c70: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
2c80: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
2c90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2ca0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
2cb0: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
2cc0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
2cd0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
2ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
2cf0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
2d00: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
2d10: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
2d20: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
2d30: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
2d40: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
2d50: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
2d60: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
2d70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2d80: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
2d90: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
2da0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
2db0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
2dc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2dd0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
2de0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
2df0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
2e00: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
2e10: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
2e20: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
2e30: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
2e40: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
2e50: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
2e60: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
2e70: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
2e80: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
2e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
2ea0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
2eb0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
2ec0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
2ed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
2ee0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
2ef0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
2f00: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
2f10: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
2f20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
2f30: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
2f40: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
2f50: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
2f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
2f70: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
2f80: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
2f90: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
2fa0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
2fb0: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
2fc0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
2fd0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
2fe0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
2ff0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
3000: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
3010: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
3020: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3030: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
3040: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
3050: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
3060: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
3070: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
3080: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
3090: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
30a0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
30b0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
30c0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
30d0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
30e0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
30f0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
3100: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
3110: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
3120: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
3130: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
3140: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3150: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
3160: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
3170: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
3180: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
3190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
31a0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
31b0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
31c0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
31d0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
31e0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
31f0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
3200: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
3210: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
3220: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
3230: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
3240: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
3250: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
3260: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
3270: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 64 65 73  result codes des
3280: 63 72 69 62 65 64 20 61 74 20 72 65 73 75 6c 74  cribed at result
3290: 2d 63 6f 64 65 73 2e 20 20 48 6f 77 65 76 65 72  -codes.  However
32a0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
32b0: 20 73 68 6f 77 6e 20 74 68 61 74 0a 2a 2a 20 6d   shown that.** m
32c0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 65 73  any of these res
32d0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
32e0: 6f 20 63 6f 75 72 73 65 2d 67 72 61 69 6e 65 64  o course-grained
32f0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
3300: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
3310: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
3320: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
3330: 75 73 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  users might like
3340: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
3350: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
3360: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
3370: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
3380: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
3390: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
33a0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
33b0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
33c0: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
33d0: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
33e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
33f0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 20 54  about errors.  T
3400: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
3410: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
3420: 62 6c 65 64 20 28 6f 72 20 64 69 73 61 62 6c 65  bled (or disable
3430: 64 29 20 66 6f 72 20 0a 2a 2a 20 65 61 63 68 20  d) for .** each 
3440: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
3450: 65 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65  ection using the
3460: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
3470: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
3480: 29 5d 20 41 50 49 2e 0a 2a 2a 20 0a 2a 2a 20 53  )] API..** .** S
3490: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c  ome of the avail
34a0: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65  able extended re
34b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c  sult codes are l
34c0: 69 73 74 65 64 20 61 62 6f 76 65 2e 0a 2a 2a 20  isted above..** 
34d0: 57 65 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  We expect the nu
34e0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
34f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
3500: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
3510: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
3520: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
3530: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3540: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
3550: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
3560: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
3570: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
3580: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 0a   of SQLite..** .
3590: 2a 2a 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20  ** The symbolic 
35a0: 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65  name for an exte
35b0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
35c0: 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69 6e 73   always contains
35d0: 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 70 72   a related.** pr
35e0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
35f0: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 20 20  e as a prefix.  
3600: 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63  Primary result c
3610: 6f 64 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73  odes contain a s
3620: 69 6e 67 6c 65 0a 2a 2a 20 22 5f 22 20 63 68 61  ingle.** "_" cha
3630: 72 61 63 74 65 72 2e 20 20 45 78 74 65 6e 64 65  racter.  Extende
3640: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63  d result codes c
3650: 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f  ontain two or mo
3660: 72 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  re "_" character
3670: 73 2e 0a 2a 2a 20 54 68 65 20 6e 75 6d 65 72 69  s..** The numeri
3680: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
3690: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
36a0: 64 65 20 63 61 6e 20 62 65 20 63 6f 6e 76 65 72  de can be conver
36b0: 74 65 64 20 74 6f 20 69 74 73 0a 2a 2a 20 63 6f  ted to its.** co
36c0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d  rresponding prim
36d0: 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ary result code 
36e0: 62 79 20 6d 61 73 6b 69 6e 67 20 6f 66 66 20 74  by masking off t
36f0: 68 65 20 6c 6f 77 65 72 20 38 20 62 79 74 65 73  he lower 8 bytes
3700: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
3710: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
3720: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
3730: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
3740: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
3750: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
3760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3770: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
3780: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
3790: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
37a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
37b0: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 28  _SHORT_READ    (
37c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
37d0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
37e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
37f0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
3800: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
3810: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
3820: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
3830: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
3840: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
3850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
3860: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
3870: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
3880: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
3890: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
38a0: 4e 43 41 54 45 20 20 20 20 20 20 28 53 51 4c 49  NCATE      (SQLI
38b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
38c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
38d0: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
38e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
38f0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
3900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
3910: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
3920: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
3930: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
3940: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
3950: 4c 4f 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  LOCK        (SQL
3960: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
3970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
3980: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
3990: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
39a0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
39b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
39c0: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
39d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
39e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
39f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
3a00: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 28  _NOMEM         (
3a10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
3a20: 31 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  12<<8))../*.** C
3a30: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
3a40: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
3a50: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 43 6f  rations.**.** Co
3a60: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65  mbination of the
3a70: 20 66 6f 6c 6c 6f 77 69 6e 67 20 62 69 74 20 76   following bit v
3a80: 61 6c 75 65 73 20 61 72 65 20 75 73 65 64 20 61  alues are used a
3a90: 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 61  s the.** third a
3aa0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
3ab0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
3ac0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
3ad0: 0a 2a 2a 20 61 73 20 66 6f 75 72 74 68 20 61 72  .** as fourth ar
3ae0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 78 4f  gument to the xO
3af0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
3b00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
3b10: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2f  s] object..**.*/
3b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3b30: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
3b40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
3b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3b60: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
3b70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
3b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3b90: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
3ba0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
3bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3bc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
3bd0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
3be0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3bf0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
3c00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
3c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3c20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
3c30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
3c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3c50: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
3c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
3c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3c80: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
3c90: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
3ca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3cb0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
3cc0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
3cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3ce0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
3cf0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
3d00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d10: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
3d20: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
3d30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d40: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
3d50: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
3d60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
3d70: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
3d80: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
3d90: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
3da0: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
3db0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
3dc0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
3dd0: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
3de0: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
3df0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
3e00: 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 62 69 74  following.** bit
3e10: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
3e20: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
3e30: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
3e40: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
3e50: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
3e60: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
3e70: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
3e80: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
3e90: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
3ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
3eb0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
3ec0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
3ed0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
3ee0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
3ef0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
3f00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
3f10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
3f20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
3f30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
3f40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
3f50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
3f60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
3f70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
3f80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
3f90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
3fa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
3fb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
3fc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
3fd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
3fe0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
3ff0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
4000: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
4010: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
4020: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
4030: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
4040: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
4050: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
4060: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
4070: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
4080: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
4090: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
40a0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
40b0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
40c0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
40d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
40e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
40f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
4100: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
4110: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4120: 35 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30  512       0x0000
4130: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
4140: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4150: 31 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  1K        0x0000
4160: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
4170: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4180: 32 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  2K        0x0000
4190: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
41a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
41b0: 34 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  4K        0x0000
41c0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
41d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
41e0: 38 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30  8K        0x0000
41f0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
4200: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4210: 31 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  16K       0x0000
4220: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
4230: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4240: 33 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  32K       0x0000
4250: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
4260: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
4270: 36 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30  64K       0x0000
4280: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
4290: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
42a0: 50 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30  PPEND     0x0000
42b0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
42c0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
42d0: 54 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30  TIAL      0x0000
42e0: 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0400../*.** CAPI
42f0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
4300: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
4310: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
4320: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
4330: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
4340: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
4350: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
4360: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
4370: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
4380: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
4390: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
43a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
43b0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
43c0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
43d0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
43e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
43f0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
4400: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
4410: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
4420: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
4430: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
4440: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
4460: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
4470: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
4480: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
4490: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
44a0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
44b0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
44c0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
44d0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
44e0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 74 20 75  ].** object it u
44f0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
4500: 6e 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  n of the followi
4510: 6e 67 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ng integer value
4520: 73 20 61 73 0a 2a 2a 20 74 68 65 20 73 65 63 6f  s as.** the seco
4530: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
4540: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
4550: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
4560: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
4570: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
4580: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
4590: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
45a0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
45b0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
45c0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
45d0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
45e0: 6c 75 73 68 65 64 2e 20 20 54 68 65 20 53 51 4c  lushed.  The SQL
45f0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
4600: 6d 65 61 6e 73 20 0a 2a 2a 20 74 6f 20 75 73 65  means .** to use
4610: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
4620: 73 65 6d 61 6e 74 69 63 73 2e 20 20 54 68 65 20  semantics.  The 
4630: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
4640: 20 66 6c 61 67 20 6d 65 61 6e 73 20 0a 2a 2a 20   flag means .** 
4650: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20  to use Mac OS-X 
4660: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
4670: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
4680: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
4690: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
46a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
46c0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
46d0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
46e0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
46f0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
4700: 30 31 30 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  010.../*.** CAPI
4710: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
4720: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
4730: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
4740: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
4750: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
4760: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
4770: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
4780: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
4790: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
47a0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
47b0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
47c0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
47d0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
47e0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
47f0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
4800: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
4810: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
4820: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
4830: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
4840: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
4850: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
4860: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
4870: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
4880: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
4890: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
48a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
48b0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
48c0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
48d0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
48e0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
48f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
4900: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
4910: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
4920: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
4930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
4940: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
4950: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
4960: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
4970: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
4980: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
4990: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  fs] xOpen method
49a0: 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69 6e   contains a poin
49b0: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73  ter to.** an ins
49c0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 74 68 69  tance of the thi
49d0: 73 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  s object.  This 
49e0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
49f0: 68 65 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73  he.** methods us
4a00: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
4a10: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
4a20: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
4a30: 6e 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  n file..**.** Th
4a40: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
4a50: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
4a60: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
4a70: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
4a80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
4a90: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
4aa0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
4ab0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
4ac0: 2a 20 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  *  The second ch
4ad0: 6f 69 63 65 20 69 73 20 61 6e 0a 2a 2a 20 4f 53  oice is an.** OS
4ae0: 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e  -X style fullsyn
4af0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53  c.  The SQLITE_S
4b00: 59 4e 43 5f 44 41 54 41 20 66 6c 61 67 20 6d 61  YNC_DATA flag ma
4b10: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 0a  y be ORed in to.
4b20: 2a 2a 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  ** indicate that
4b30: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
4b40: 66 20 74 68 65 20 66 69 6c 65 20 61 6e 64 20 6e  f the file and n
4b50: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
4b60: 64 73 20 74 6f 20 62 65 0a 2a 2a 20 73 79 6e 63  ds to be.** sync
4b70: 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 69  ed..** .** The i
4b80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
4b90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
4ba0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
4bb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
4bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
4bd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
4be0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
4bf0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
4c00: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
4c10: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
4c20: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
4c30: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
4c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
4c50: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
4c60: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
4c70: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
4c80: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
4c90: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 20 0a 2a  es the lock.  .*
4ca0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
4cb0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
4cc0: 64 20 6c 6f 6f 6b 73 0a 2a 2a 20 74 6f 20 73 65  d looks.** to se
4cd0: 65 20 69 66 20 61 6e 79 20 64 61 74 61 62 61 73  e if any databas
4ce0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 65 69  e connection, ei
4cf0: 74 68 65 72 20 69 6e 20 74 68 69 73 0a 2a 2a 20  ther in this.** 
4d00: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
4d10: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
4d20: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 6e 20  , is holding an 
4d30: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
4d40: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
4d50: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
4d60: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
4d70: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
4d80: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
4d90: 6e 64 20 66 61 6c 73 65 20 69 66 20 6e 6f 74 2e  nd false if not.
4da0: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 78 46 69 6c  .** .** The xFil
4db0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
4dc0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
4dd0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
4de0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
4df0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
4e00: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
4e10: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
4e20: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
4e30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
4e40: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
4e50: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
4e60: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 0a 2a   "op" argument.*
4e70: 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  * is an integer 
4e80: 6f 70 63 6f 64 65 2e 20 20 20 54 68 65 20 74 68  opcode.   The th
4e90: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
4ea0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
4eb0: 6e 74 65 72 20 77 68 69 63 68 20 69 73 20 69 6e  nter which is in
4ec0: 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 70  tended to be a p
4ed0: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73  ointer.** to a s
4ee0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
4ef0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
4f00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
4f10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
4f20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
4f30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
4f40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
4f50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
4f60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
4f70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
4f80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
4f90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
4fa0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
4fb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
4fc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
4fd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
4fe0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
4ff0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
5000: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
5010: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
5020: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
5030: 72 65 73 65 72 76 65 73 20 6f 70 63 6f 64 65 73  reserves opcodes
5040: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
5050: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 20  or its own use. 
5060: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
5070: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
5080: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
5090: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
50a0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
50b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
50c0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
50d0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
50e0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
50f0: 20 6f 70 63 6f 64 65 73 20 0a 2a 2a 20 67 72 65   opcodes .** gre
5100: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
5110: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
5120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
5130: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
5140: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
5150: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
5160: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
5170: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
5180: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
5190: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
51a0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
51b0: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
51c0: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
51d0: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
51e0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
51f0: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
5200: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
5210: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
5220: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
5230: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
5240: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
5250: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
5260: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
5270: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5280: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
5290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
52a0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
52b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
52c0: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
52d0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
52e0: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
52f0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5300: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
5310: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5320: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
5330: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
5340: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
5350: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
5360: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
5370: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
5380: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
5390: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
53a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
53b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
53c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
53d0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
53e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
53f0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5400: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5410: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5420: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5430: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5440: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5450: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
5460: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
5470: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
5480: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
5490: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
54a0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
54b0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
54c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
54d0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
54e0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
54f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5500: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5510: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5520: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5530: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5540: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5550: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
5560: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
5570: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
5580: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
5590: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
55a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
55b0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
55c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
55d0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
55e0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
55f0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5600: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5610: 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  rite()..*/.typed
5620: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5630: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
5640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
5650: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
5660: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
5670: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
5680: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
5690: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
56a0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
56b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
56c0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
56d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
56e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
56f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5700: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
5710: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
5720: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
5730: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
5740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5750: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
5760: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
5770: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
5780: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
5790: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
57a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
57b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
57c0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
57d0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
57e0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
57f0: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
5800: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
5810: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
5820: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
5830: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
5840: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
5850: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
5860: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
5870: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
5880: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
5890: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
58a0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
58b0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
58c0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
58d0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
58e0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
58f0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
5900: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
5910: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
5920: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
5930: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
5940: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
5950: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
5960: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
5970: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
5980: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
5990: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
59a0: 62 6a 65 63 74 20 61 6e 64 20 74 6f 20 74 68 65  bject and to the
59b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
59c0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
59d0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
59e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
59f0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
5a00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
5a10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
5a20: 2a 20 6f 70 63 6f 64 65 20 63 61 73 65 73 20 74  * opcode cases t
5a30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
5a40: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
5a50: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
5a60: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
5a70: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
5a80: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
5a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5aa0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
5ab0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [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 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
5ae0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
5af0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
5b00: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
5b10: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
5b20: 73 20 74 6f 2e 20 20 54 68 69 73 20 63 61 70 61  s to.  This capa
5b30: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
5b40: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
5b50: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
5b60: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
5b70: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
5b80: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
5bb0: 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a  E        1../*.*
5bc0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
5bd0: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
5be0: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
5bf0: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
5c00: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
5c10: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
5c20: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
5c30: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
5c40: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
5c50: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
5c60: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
5c70: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
5c80: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
5c90: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
5ca0: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
5cb0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
5cc0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
5cd0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
5ce0: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
5cf0: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
5d00: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
5d10: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
5d20: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
5d30: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
5d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5d50: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
5d60: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
5d70: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
5d80: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
5d90: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
5da0: 77 65 65 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  ween the.** SQLi
5db0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
5dc0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
5dd0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
5de0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
5df0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
5e00: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
5e10: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
5e20: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
5e30: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
5e40: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
5e50: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
5e60: 20 66 6f 72 20 66 75 74 75 72 65 0a 2a 2a 20 76   for future.** v
5e70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
5e80: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
5e90: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
5ea0: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
5eb0: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
5ec0: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
5ed0: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 0a 2a 2a  is increased..**
5ee0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
5ef0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
5f00: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
5f10: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
5f20: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
5f30: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
5f40: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
5f50: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
5f60: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
5f70: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
5f80: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
5f90: 72 65 64 20 76 66 73 20 6d 6f 64 75 6c 65 73 20  red vfs modules 
5fa0: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
5fb0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
5fc0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
5fd0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
5fe0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
5ff0: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
6000: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
6010: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
6020: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
6030: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
6040: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
6050: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
6060: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
6070: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
6080: 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54  he list..**.** T
6090: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
60a0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
60b0: 73 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  s in the sqlite3
60c0: 5f 76 66 73 20 0a 2a 2a 20 73 74 72 75 63 74 75  _vfs .** structu
60d0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
60e0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
60f0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
6100: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
6110: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
6120: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
6130: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
6140: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
6150: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6160: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
6170: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
6180: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
6190: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
61a0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
61b0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
61c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
61d0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
61e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
61f0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
6200: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
6210: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
6220: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
6230: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
6240: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
6250: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
6260: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  ng passed to.** 
6270: 78 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c  xOpen() is a ful
6280: 6c 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65  l pathname as ge
6290: 6e 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c  nerated by xFull
62a0: 50 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 2a  Pathname() and.*
62b0: 2a 20 74 68 61 74 20 74 68 65 20 73 74 72 69 6e  * that the strin
62c0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
62d0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
62e0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
62f0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 20 53 6f 20 74  ** called.  So t
6300: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
6310: 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20 70 6f  ] can store a po
6320: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
6330: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
6340: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
6350: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
6360: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
6370: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
6380: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
6390: 28 29 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  () is a copy of 
63a0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
63b0: 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
63c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 49  3_open_v2()].  I
63d0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
63e0: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
63f0: 70 65 6e 31 36 28 29 5d 0a 2a 2a 20 69 73 20 75  pen16()].** is u
6400: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
6410: 69 73 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  is [SQLITE_OPEN_
6420: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
6440: 5d 2e 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  ]..** If xOpen()
6450: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
6460: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
6470: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
6480: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
6490: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
64a0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
64b0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
64c0: 6d 61 79 20 62 65 0a 2a 2a 20 73 65 74 2e 0a 2a  may be.** set..*
64d0: 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  * .** SQLite wil
64e0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
64f0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
6500: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
6510: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
6520: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
6530: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
6540: 65 64 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ed:.** .** <ul>.
6550: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
6560: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
6570: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
6580: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6590: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
65a0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
65b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
65c0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
65d0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
65e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
65f0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
6600: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
6610: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
6620: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
6630: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
6640: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6650: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
6660: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
6670: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
6680: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
6690: 20 63 68 61 6e 67 65 73 20 74 68 65 20 77 61 79   changes the way
66a0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
66b0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
66c0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
66d0: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
66e0: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
66f0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
6700: 20 72 6f 6c 6c 62 61 63 6b 2c 20 6d 69 67 68 74   rollback, might
6710: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
6720: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
6730: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
6740: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
6750: 72 6e 61 6c 20 61 72 65 0a 2a 2a 20 61 6c 73 6f  rnal are.** also
6760: 20 61 20 6e 6f 2d 6f 70 2e 20 20 41 6e 79 20 61   a no-op.  Any a
6770: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
6780: 68 65 20 6a 6f 75 72 6e 61 6c 20 72 65 74 75 72  he journal retur
6790: 6e 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 0a  n SQLITE_IOERR..
67a0: 2a 2a 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  ** Or the implem
67b0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
67c0: 65 63 6f 67 6e 69 7a 65 20 74 68 65 20 61 20 64  ecognize the a d
67d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
67e0: 6c 0a 2a 2a 20 62 65 20 64 6f 69 6e 67 20 70 61  l.** be doing pa
67f0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
6800: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
6810: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 20 6f  es in a random o
6820: 72 64 65 72 0a 2a 2a 20 61 6e 64 20 73 65 74 20  rder.** and set 
6830: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
6840: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
6850: 2e 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20  ..** .** SQLite 
6860: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
6870: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
6880: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
6890: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 65 74 68 6f 64   xOpen.** method
68a0: 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
68b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
68c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
68d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
68e0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
68f0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ].** </ul>.** .*
6900: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
6910: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6920: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
6930: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
6940: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
6950: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54  it is closed.  T
6960: 68 69 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  his will always 
6970: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
6980: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 20 61 6e  .** databases an
6990: 64 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66  d journals and f
69a0: 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20  or subjournals. 
69b0: 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   The .** [SQLITE
69c0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
69d0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
69e0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
69f0: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
6a00: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
6a10: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
6a20: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
6a30: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
6a40: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
6a50: 69 6c 65 2e 0a 2a 2a 20 0a 2a 2a 20 53 70 61 63  ile..** .** Spac
6a60: 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  e to hold the  [
6a70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
6a80: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
6a90: 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20  s the third .** 
6aa0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
6ab0: 6e 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  n is allocated b
6ac0: 79 20 63 61 6c 6c 65 72 20 28 74 68 65 20 53 51  y caller (the SQ
6ad0: 4c 69 74 65 20 63 6f 72 65 29 2e 20 0a 2a 2a 20  Lite core). .** 
6ae0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 61  szOsFile bytes a
6af0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72  re allocated for
6b00: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20 54   this object.  T
6b10: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 0a  he xOpen method.
6b20: 2a 2a 20 66 69 6c 6c 73 20 69 6e 20 74 68 65 20  ** fills in the 
6b30: 61 6c 6c 6f 63 61 74 65 64 20 73 70 61 63 65 2e  allocated space.
6b40: 0a 2a 2a 20 0a 2a 2a 20 54 68 65 20 66 6c 61 67  .** .** The flag
6b50: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
6b60: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
6b70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
6b80: 49 53 54 53 5d 20 0a 2a 2a 20 74 6f 20 74 65 73  ISTS] .** to tes
6b90: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 61  t for the exista
6ba0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 0a 2a  nce of a file,.*
6bb0: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  * or [SQLITE_ACC
6bc0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
6bd0: 6f 20 74 65 73 74 20 74 6f 20 73 65 65 0a 2a 2a  o test to see.**
6be0: 20 69 66 20 61 20 66 69 6c 65 20 69 73 20 72 65   if a file is re
6bf0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
6c00: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
6c10: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
6c20: 74 6f 20 74 65 73 74 20 74 6f 20 73 65 65 20 69  to test to see i
6c30: 66 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  f a file is at l
6c40: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
6c50: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
6c60: 61 20 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e  a .** directory.
6c70: 0a 2a 2a 20 0a 2a 2a 20 53 51 4c 69 74 65 20 77  .** .** SQLite w
6c80: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
6c90: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
6ca0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 20 66  athname+1 byte f
6cb0: 6f 72 0a 2a 2a 20 74 68 65 20 6f 75 74 70 75 74  or.** the output
6cc0: 20 62 75 66 66 65 72 73 20 66 6f 72 20 78 47 65   buffers for xGe
6cd0: 74 54 65 6d 70 6e 61 6d 65 20 61 6e 64 20 78 46  tTempname and xF
6ce0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 54 68 65  ullPathname. The
6cf0: 20 65 78 61 63 74 0a 2a 2a 20 73 69 7a 65 20 6f   exact.** size o
6d00: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
6d10: 66 65 72 20 69 73 20 61 6c 73 6f 20 70 61 73 73  fer is also pass
6d20: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
6d30: 72 20 74 6f 20 62 6f 74 68 20 0a 2a 2a 20 6d 65  r to both .** me
6d40: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
6d50: 74 70 75 74 20 62 75 66 66 65 72 20 69 73 20 6e  tput buffer is n
6d60: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
6d70: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
6d80: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
6d90: 74 75 72 6e 65 64 2e 20 41 73 20 74 68 69 73 20  turned. As this 
6da0: 69 73 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  is handled as a 
6db0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
6dc0: 51 4c 69 74 65 2c 0a 2a 2a 20 76 66 73 20 69 6d  QLite,.** vfs im
6dd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
6de0: 6f 75 6c 64 20 65 6e 64 65 76 6f 75 72 20 74 6f  ould endevour to
6df0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
6e00: 20 73 65 74 74 69 6e 67 20 0a 2a 2a 20 6d 78 50   setting .** mxP
6e10: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
6e20: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
6e30: 76 61 6c 75 65 2e 0a 2a 2a 20 0a 2a 2a 20 54 68  value..** .** Th
6e40: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
6e50: 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78   xSleep(), and x
6e60: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e  CurrentTime() in
6e70: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
6e80: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
6e90: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
6ea0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
6eb0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
6ec0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
6ed0: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
6ee0: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
6ef0: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
6f00: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
6f10: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
6f20: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
6f30: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
6f40: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
6f50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
6f60: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
6f70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
6f80: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
6f90: 62 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 2a 2a  btained.  The.**
6fa0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
6fb0: 20 63 61 75 73 65 20 74 68 65 20 63 61 6c 6c 69   cause the calli
6fc0: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
6fd0: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
6fe0: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
6ff0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
7000: 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65  ven.  The xCurre
7010: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
7020: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
7030: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
7040: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
7050: 61 74 65 20 61 6e 64 0a 2a 2a 20 74 69 6d 65 2e  ate and.** time.
7060: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7070: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
7080: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75  qlite3_vfs;.stru
7090: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
70a0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
70b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
70c0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
70d0: 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74   number */.  int
70e0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
70f0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
7100: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
7110: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
7120: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
7130: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
7140: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
7150: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
7160: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
7170: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
7180: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
7190: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
71a0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
71b0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
71c0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
71d0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
71e0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
71f0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
7200: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
7210: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
7220: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
7230: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
7240: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
7250: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
7260: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
7270: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
7280: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
7290: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
72a0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
72b0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
72c0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
72d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
72e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
72f0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  e, int flags);. 
7300: 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70 6e   int (*xGetTempn
7310: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
7320: 2a 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  *, int nOut, cha
7330: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
7340: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
7350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
7360: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
7370: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
7380: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
7390: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
73a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
73b0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
73c0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
73d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
73e0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
73f0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
7400: 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28  void *(*xDlSym)(
7410: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
7420: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
7430: 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64  zSymbol);.  void
7440: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
7450: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
7460: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
7470: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
7480: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
7490: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
74a0: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
74b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
74c0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
74d0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
74e0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
74f0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f  *, double*);.  /
7500: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
7510: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
7520: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
7530: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
7540: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
7550: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
7560: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
7570: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7580: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
7590: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
75a0: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
75b0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
75c0: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
75d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
75e0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
75f0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
7600: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
7610: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
7620: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
7630: 20 74 68 65 20 6b 69 6e 64 20 6f 66 20 77 68 61   the kind of wha
7640: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
7650: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
7660: 73 20 6d 65 74 68 6f 64 20 69 73 0a 2a 2a 20 6c  s method is.** l
7670: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 20 20 57 69 74  ooking for.  Wit
7680: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
7690: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
76a0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
76b0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 74 6f 20 73  mply checks to s
76c0: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 65  ee if the file e
76d0: 78 69 73 74 73 2e 20 20 57 69 74 68 20 53 51 4c  xists.  With SQL
76e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
76f0: 52 49 54 45 2c 0a 2a 2a 20 74 68 65 20 78 41 63  RITE,.** the xAc
7700: 63 65 73 73 20 6d 65 74 68 6f 64 20 63 68 65 63  cess method chec
7710: 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks to see if the
7720: 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65   file is both re
7730: 61 64 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 77 72  adable.** and wr
7740: 69 74 61 62 6c 65 2e 20 20 57 69 74 68 20 53 51  itable.  With SQ
7750: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
7760: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
7770: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 74 6f  hod.** checks to
7780: 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c 65   see if the file
7790: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
77a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
77b0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
77c0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
77d0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
77e0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
77f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
7800: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
7810: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
7820: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
7830: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
7840: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
7850: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
7860: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 53  sables the.** [S
7870: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
7880: 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75   | extended resu
7890: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
78a0: 65 2e 0a 2a 2a 20 42 79 20 64 65 66 61 75 6c 74  e..** By default
78b0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
78c0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
78d0: 20 6f 66 20 6f 6e 6c 79 20 32 36 20 69 6e 74 65   of only 26 inte
78e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
78f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
7900: 5d 2e 20 20 57 68 65 6e 20 65 78 74 65 6e 64 65  ].  When extende
7910: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 0a 2a  d result codes.*
7920: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  * are enabled by
7930: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
7940: 68 65 20 72 65 70 65 74 6f 69 72 65 20 6f 66 20  he repetoire of 
7950: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 63 61 6e  result codes can
7960: 20 62 65 0a 2a 2a 20 6d 75 63 68 20 6c 61 72 67   be.** much larg
7970: 65 72 20 61 6e 64 20 63 61 6e 20 28 68 6f 70 65  er and can (hope
7980: 66 75 6c 6c 79 29 20 70 72 6f 76 69 64 65 20 6d  fully) provide m
7990: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
79a0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
79b0: 74 20 74 68 65 20 63 61 75 73 65 20 6f 66 20 61  t the cause of a
79c0: 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
79d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
79e0: 6e 74 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  nt is a boolean 
79f0: 76 61 6c 75 65 20 74 68 61 74 20 74 75 72 6e 73  value that turns
7a00: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
7a10: 0a 2a 2a 20 63 6f 64 65 73 20 6f 6e 20 61 6e 64  .** codes on and
7a20: 20 6f 66 66 2e 20 20 45 78 74 65 6e 64 65 64 20   off.  Extended 
7a30: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
7a40: 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 20   off by default 
7a50: 66 6f 72 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  for.** backwards
7a60: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
7a70: 69 74 68 20 6f 6c 64 65 72 20 76 65 72 73 69 6f  ith older versio
7a80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
7a90: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
7aa0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
7ab0: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
7ac0: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
7ad0: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
7ae0: 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
7af0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
7b00: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
7b10: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
7b20: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
7b30: 65 72 20 6b 65 79 0a 2a 2a 20 63 61 6c 6c 65 64  er key.** called
7b40: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
7b50: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
7b60: 73 20 61 76 61 69 6c 61 62 6c 65 20 61 73 20 61  s available as a
7b70: 6e 20 75 6e 64 65 63 6c 61 72 65 64 0a 2a 2a 20  n undeclared.** 
7b80: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
7b90: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
7ba0: 49 44 5f 2e 20 20 49 66 20 74 68 65 20 74 61 62  ID_.  If the tab
7bb0: 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
7bc0: 6f 66 0a 2a 2a 20 74 79 70 65 20 49 4e 54 45 47  of.** type INTEG
7bd0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
7be0: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20  hen that column 
7bf0: 69 73 20 61 6e 6f 74 68 65 72 20 61 6e 20 61 6c  is another an al
7c00: 69 61 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 72  ias for the.** r
7c10: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
7c20: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
7c30: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
7c40: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
7c50: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
7c60: 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 64 61 74 61  into.** the data
7c70: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 64 61  base from the da
7c80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7c90: 6e 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 66  n given in the f
7ca0: 69 72 73 74 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  irst .** argumen
7cb0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
7cc0: 73 66 75 6c 20 69 6e 73 65 72 74 73 20 68 61 76  sful inserts hav
7cd0: 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
7ce0: 6f 6e 20 74 68 69 73 20 64 61 74 61 62 61 73 65  on this database
7cf0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  .** connection, 
7d00: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
7d10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
7d20: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
7d30: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
7d40: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
7d50: 74 68 65 0a 2a 2a 20 69 6e 73 65 72 74 65 64 20  the.** inserted 
7d60: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
7d70: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
7d80: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
7d90: 72 69 67 67 65 72 0a 2a 2a 20 69 73 20 72 75 6e  rigger.** is run
7da0: 6e 69 6e 67 2e 20 20 42 75 74 20 6f 6e 63 65 20  ning.  But once 
7db0: 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
7dc0: 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
7dd0: 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
7de0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
7df0: 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
7e00: 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
7e10: 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 74   before the.** t
7e20: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
7e30: 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68  .** An INSERT th
7e40: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
7e50: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
7e60: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
7e70: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e  ** successful in
7e80: 73 65 72 74 20 61 6e 64 20 64 6f 65 73 20 6e 6f  sert and does no
7e90: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
7ea0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
7eb0: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
7ec0: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20   Thus INSERT OR 
7ed0: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
7ee0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
7ef0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
7f00: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
7f10: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
7f20: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
7f30: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
7f40: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
7f50: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
7f60: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45  ails.  When INSE
7f70: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 0a 2a  RT OR REPLACE .*
7f80: 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
7f90: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
7fa0: 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
7fb0: 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
7fc0: 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
7fd0: 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
7fe0: 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
7ff0: 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
8000: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
8010: 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
8020: 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
8030: 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
8040: 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
8050: 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
8060: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
8070: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 64  another thread d
8080: 6f 65 73 20 61 20 6e 65 77 20 69 6e 73 65 72 74  oes a new insert
8090: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
80a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
80b0: 0a 2a 2a 20 77 68 69 6c 65 20 74 68 69 73 20 72  .** while this r
80c0: 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
80d0: 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
80e0: 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
80f0: 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 74 68 65  rt rowid,.** the
8100: 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
8110: 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ue of this routi
8120: 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ne is undefined.
8130: 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
8140: 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
8150: 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
8160: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
8170: 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
8180: 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
8190: 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
81a0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
81b0: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
81c0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
81d0: 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
81e0: 67 65 64 0a 2a 2a 20 28 6f 72 20 69 6e 73 65 72  ged.** (or inser
81f0: 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 29 20  ted or deleted) 
8200: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
8210: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
8220: 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 63 68 61 6e 67  .  Only.** chang
8230: 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
8240: 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
8250: 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
8260: 44 41 54 45 2c 20 6f 72 0a 2a 2a 20 44 45 4c 45  DATE, or.** DELE
8270: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
8280: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
8290: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
82a0: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
82b0: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
82c0: 65 64 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71  ed.  Use the [sq
82d0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
82e0: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a  ges()] function.
82f0: 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  ** to find the t
8300: 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
8310: 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67  hanges including
8320: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
8330: 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a  by triggers..**.
8340: 2a 2a 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  ** Within the bo
8350: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
8360: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
8370: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
8380: 20 63 61 6e 20 62 65 0a 2a 2a 20 63 61 6c 6c 65   can be.** calle
8390: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
83a0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
83b0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
83c0: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
83d0: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
83e0: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
83f0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
8400: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
8410: 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  trigger..**.** A
8420: 6c 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  ll changes are c
8430: 6f 75 6e 74 65 64 2c 20 65 76 65 6e 20 69 66 20  ounted, even if 
8440: 74 68 65 79 20 77 65 72 65 20 6c 61 74 65 72 20  they were later 
8450: 75 6e 64 6f 6e 65 20 62 79 20 61 0a 2a 2a 20 52  undone by a.** R
8460: 4f 4c 4c 42 41 43 4b 20 6f 72 20 41 42 4f 52 54  OLLBACK or ABORT
8470: 2e 20 20 45 78 63 65 70 74 2c 20 63 68 61 6e 67  .  Except, chang
8480: 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  es associated wi
8490: 74 68 20 63 72 65 61 74 69 6e 67 20 61 6e 64 0a  th creating and.
84a0: 2a 2a 20 64 72 6f 70 70 69 6e 67 20 74 61 62 6c  ** dropping tabl
84b0: 65 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  es are not count
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ed..**.** If a c
84d0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 6b 65 73 20  allback invokes 
84e0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
84f0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
8500: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
8510: 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 68  ,.** then the ch
8520: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 69 6e 6e  anges in the inn
8530: 65 72 2c 20 72 65 63 75 72 73 69 76 65 20 63 61  er, recursive ca
8540: 6c 6c 20 61 72 65 20 63 6f 75 6e 74 65 64 20 74  ll are counted t
8550: 6f 67 65 74 68 65 72 0a 2a 2a 20 77 69 74 68 20  ogether.** with 
8560: 74 68 65 20 63 68 61 6e 67 65 73 20 69 6e 20 74  the changes in t
8570: 68 65 20 6f 75 74 65 72 20 63 61 6c 6c 2e 0a 2a  he outer call..*
8580: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
8590: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
85a0: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
85b0: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
85c0: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
85d0: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
85e0: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
85f0: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
8600: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
8610: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
8620: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
8630: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
8640: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
8650: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
8660: 0a 2a 2a 20 74 68 69 73 20 6f 70 74 69 6d 69 7a  .** this optimiz
8670: 61 74 69 6f 6e 2c 20 74 68 65 20 63 68 61 6e 67  ation, the chang
8680: 65 20 63 6f 75 6e 74 20 66 6f 72 20 22 44 45 4c  e count for "DEL
8690: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
86a0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 7a 65 72 6f 20  will be.** zero 
86b0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
86c0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d  e number of elem
86d0: 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f  ents that were o
86e0: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
86f0: 0a 2a 2a 20 74 61 62 6c 65 2e 20 54 6f 20 67 65  .** table. To ge
8700: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
8710: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
8720: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
8730: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
8740: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
8750: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
8760: 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
8770: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
8780: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
8790: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
87a0: 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 74 68  tion.** while th
87b0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
87c0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 72  nning then the r
87d0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
87e0: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69  his routine.** i
87f0: 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
8800: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
8810: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
8820: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8830: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
8840: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
8850: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
8860: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
8870: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
8880: 65 20 72 6f 77 73 20 74 68 61 74 20 68 61 76 65  e rows that have
8890: 20 62 65 65 6e 0a 2a 2a 20 6d 6f 64 69 66 69 65   been.** modifie
88a0: 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44  d by INSERT, UPD
88b0: 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
88c0: 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
88d0: 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
88e0: 6c 65 0a 2a 2a 20 77 61 73 20 6f 70 65 6e 65 64  le.** was opened
88f0: 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
8900: 55 50 44 41 54 45 2c 20 49 4e 53 45 52 54 20 61  UPDATE, INSERT a
8910: 6e 64 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  nd DELETE statem
8920: 65 6e 74 73 20 65 78 65 63 75 74 65 64 0a 2a 2a  ents executed.**
8930: 20 61 73 20 70 61 72 74 20 6f 66 20 74 72 69 67   as part of trig
8940: 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 41 6c  ger programs. Al
8950: 6c 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  l changes are co
8960: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
8970: 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
8980: 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
8990: 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
89a0: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
89b0: 6e 74 20 68 61 6e 64 6c 65 20 69 73 0a 2a 2a 20  nt handle is.** 
89c0: 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
89d0: 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
89e0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
89f0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
8a00: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
8a10: 33 5f 63 68 61 6e 67 65 28 29 5d 20 69 6e 74 65  3_change()] inte
8a20: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  rface..**.** SQL
8a30: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
8a40: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
8a50: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
8a60: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63  ithout a WHERE c
8a70: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70  lause.** by drop
8a80: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
8a90: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
8aa0: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  (This is much fa
8ab0: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
8ac0: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
8ad0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
8ae0: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 6f 72 6d  al elements form
8af0: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
8b00: 63 61 75 73 65 20 6f 66 0a 2a 2a 20 74 68 69 73  cause of.** this
8b10: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
8b20: 68 65 20 63 68 61 6e 67 65 20 63 6f 75 6e 74 20  he change count 
8b30: 66 6f 72 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  for "DELETE FROM
8b40: 20 74 61 62 6c 65 22 20 77 69 6c 6c 20 62 65 0a   table" will be.
8b50: 2a 2a 20 7a 65 72 6f 20 72 65 67 61 72 64 6c 65  ** zero regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
8b70: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
8b80: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
8b90: 79 20 69 6e 20 74 68 65 0a 2a 2a 20 74 61 62 6c  y in the.** tabl
8ba0: 65 2e 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  e. To get an acc
8bb0: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
8bc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
8bd0: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
8be0: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
8bf0: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
8c00: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  stead..**.** If 
8c10: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 6d  another thread m
8c20: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
8c30: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
8c40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
8c50: 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
8c60: 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ne is running th
8c70: 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
8c80: 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
8c90: 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ine.** is undefi
8ca0: 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
8cb0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
8cc0: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
8cd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
8ce0: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
8cf0: 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
8d00: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
8d10: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
8d20: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
8d30: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
8d40: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
8d50: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
8d60: 70 6f 72 74 75 6e 69 74 79 2e 20 20 54 68 69 73  portunity.  This
8d70: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
8d80: 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
8d90: 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
8da0: 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
8db0: 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
8dc0: 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
8dd0: 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
8de0: 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
8df0: 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
8e00: 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
8e10: 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  iately..**.** It
8e20: 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
8e30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
8e40: 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
8e50: 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
8e60: 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
8e70: 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
8e80: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
8e90: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
8ea0: 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
8eb0: 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
8ec0: 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 64 61  outine with a da
8ed0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8ee0: 6e 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  n that.** is clo
8ef0: 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
8f00: 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
8f10: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
8f20: 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
8f30: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
8f40: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
8f50: 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
8f60: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
8f70: 5d 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  ]..** If an inte
8f80: 72 72 75 70 74 65 64 20 6f 70 65 72 61 74 69 6f  rrupted operatio
8f90: 6e 20 77 61 73 20 61 6e 20 75 70 64 61 74 65 20  n was an update 
8fa0: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
8fb0: 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
8fc0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
8fd0: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
8fe0: 61 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 72  action will be r
8ff0: 6f 6c 6c 65 64 0a 2a 2a 20 62 61 63 6b 20 61 75  olled.** back au
9000: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2f 0a  tomatically..*/.
9010: 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
9020: 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
9030: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9040: 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
9050: 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
9060: 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
9070: 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
9080: 6e 73 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ns return true i
9090: 66 20 74 68 65 20 67 69 76 65 6e 20 69 6e 70 75  f the given inpu
90a0: 74 20 73 74 72 69 6e 67 20 63 6f 6d 70 72 69 73  t string compris
90b0: 65 73 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  es.** one or mor
90c0: 65 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  e complete SQL s
90d0: 74 61 74 65 6d 65 6e 74 73 2e 20 46 6f 72 20 74  tatements. For t
90e0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  he sqlite3_compl
90f0: 65 74 65 28 29 20 63 61 6c 6c 2c 0a 2a 2a 20 74  ete() call,.** t
9100: 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  he parameter mus
9110: 74 20 62 65 20 61 20 6e 75 6c 2d 74 65 72 6d 69  t be a nul-termi
9120: 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
9130: 6e 67 2e 20 46 6f 72 0a 2a 2a 20 73 71 6c 69 74  ng. For.** sqlit
9140: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2c  e3_complete16(),
9150: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
9160: 64 20 6d 61 63 68 69 6e 65 20 62 79 74 65 20 6f  d machine byte o
9170: 72 64 65 72 20 55 54 46 2d 31 36 20 73 74 72 69  rder UTF-16 stri
9180: 6e 67 0a 2a 2a 20 69 73 20 72 65 71 75 69 72 65  ng.** is require
9190: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
91a0: 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
91b0: 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c  ul for command-l
91c0: 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
91d0: 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
91e0: 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
91f0: 65 64 20 74 65 78 74 20 66 6f 72 6d 73 20 6f 6e  ed text forms on
9200: 65 20 6f 72 20 6d 6f 72 65 20 63 6f 6d 70 6c 65  e or more comple
9210: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
9220: 73 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  s or.** if addit
9230: 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
9240: 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
9250: 64 69 6e 67 20 74 68 65 20 73 74 61 74 65 6d 65  ding the stateme
9260: 6e 74 73 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  nts into.** SQLi
9270: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
9280: 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  The algorithm is
9290: 20 73 69 6d 70 6c 65 2e 20 20 49 66 20 74 68 65   simple.  If the
92a0: 20 0a 2a 2a 20 6c 61 73 74 20 74 6f 6b 65 6e 20   .** last token 
92b0: 6f 74 68 65 72 20 74 68 61 6e 20 73 70 61 63 65  other than space
92c0: 73 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 69  s and comments i
92d0: 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 2c 20 74  s a semicolon, t
92e0: 68 65 6e 20 72 65 74 75 72 6e 20 0a 2a 2a 20 74  hen return .** t
92f0: 72 75 65 2e 20 20 41 63 74 75 61 6c 6c 79 2c 20  rue.  Actually, 
9300: 74 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 69 73  the algorithm is
9310: 20 61 20 6c 69 74 74 6c 65 20 6d 6f 72 65 20 63   a little more c
9320: 6f 6d 70 6c 69 63 61 74 65 64 20 74 68 61 6e 20  omplicated than 
9330: 74 68 61 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  that.** in order
9340: 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 74 72   to deal with tr
9350: 69 67 67 65 72 73 2c 20 62 75 74 20 74 68 65 20  iggers, but the 
9360: 62 61 73 69 63 20 69 64 65 61 20 69 73 20 74 68  basic idea is th
9370: 65 20 73 61 6d 65 3a 20 20 74 68 65 0a 2a 2a 20  e same:  the.** 
9380: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
9390: 20 63 6f 6d 70 6c 65 74 65 20 75 6e 6c 65 73 73   complete unless
93a0: 20 69 74 20 65 6e 64 73 20 69 6e 20 61 20 73 65   it ends in a se
93b0: 6d 69 63 6f 6c 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  micolon..*/.int 
93c0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
93d0: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
93e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
93f0: 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
9400: 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
9410: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
9420: 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
9430: 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
9440: 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
9450: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
9460: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 63 61   identifies a ca
9470: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
9480: 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
9490: 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76 65  voked.** wheneve
94a0: 72 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  r an attempt is 
94b0: 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
94c0: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 0a 2a  atabase table .*
94d0: 2a 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  * that another t
94e0: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
94f0: 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20   has locked..** 
9500: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
9510: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
9520: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
9530: 0a 2a 2a 20 28 6f 72 20 73 6f 6d 65 74 69 6d 65  .** (or sometime
9540: 73 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  s [SQLITE_IOERR_
9550: 42 4c 4f 43 4b 45 44 5d 29 0a 2a 2a 20 69 73 20  BLOCKED]).** is 
9560: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
9570: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
9580: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
9590: 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79 20  .** If the busy 
95a0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20  callback is not 
95b0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 0a 2a  NULL, then the.*
95c0: 2a 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  * callback will 
95d0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
95e0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  two arguments.  
95f0: 54 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  The.** first arg
9600: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
9610: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
9620: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
9630: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
9640: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
9650: 6e 74 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  nt to this routi
9660: 6e 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ne.  The second 
9670: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
9680: 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 74 68  he handler is th
9690: 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
96a0: 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
96b0: 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
96c0: 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
96d0: 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
96e0: 6e 74 2e 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  nt. If the.** bu
96f0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
9700: 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
9710: 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
9720: 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
9730: 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
9740: 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
9750: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
9760: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
9770: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
9780: 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
9790: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
97a0: 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
97b0: 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
97c0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 0a 2a 2a 20   to open the.** 
97d0: 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
97e0: 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
97f0: 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
9800: 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
9810: 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
9820: 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
9830: 74 65 65 20 74 68 61 74 0a 2a 2a 20 69 74 20 77  tee that.** it w
9840: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
9850: 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
9860: 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 0a 2a 2a  k contention..**
9870: 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
9880: 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
9890: 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
98a0: 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
98b0: 74 20 69 6e 0a 2a 2a 20 61 20 64 65 61 64 6c 6f  t in.** a deadlo
98c0: 63 6b 2c 20 69 74 20 77 69 6c 6c 20 72 65 74 75  ck, it will retu
98d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
98e0: 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 20 43 6f 6e   instead..** Con
98f0: 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
9900: 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
9910: 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
9920: 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
9930: 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
9940: 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
9950: 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
9960: 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
9970: 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
9980: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
9990: 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
99a0: 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
99b0: 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
99c0: 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
99d0: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
99e0: 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
99f0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
9a00: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
9a10: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
9a20: 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
9a30: 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
9a40: 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
9a50: 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
9a60: 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
9a70: 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
9a80: 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
9a90: 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
9aa0: 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
9ab0: 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
9ac0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
9ad0: 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
9ae0: 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
9af0: 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
9b00: 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
9b10: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
9b20: 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
9b30: 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
9b40: 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
9b50: 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
9b60: 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
9b70: 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
9b80: 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
9b90: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
9ba0: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
9bb0: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
9bc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
9bd0: 45 44 5d 20 77 68 65 6e 0a 2a 2a 20 53 51 4c 69  ED] when.** SQLi
9be0: 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
9bf0: 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
9c00: 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
9c10: 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
9c20: 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
9c30: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
9c40: 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
9c50: 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
9c60: 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
9c70: 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
9c80: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
9c90: 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
9ca0: 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
9cb0: 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
9cc0: 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
9cd0: 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
9ce0: 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
9cf0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
9d00: 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
9d10: 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
9d20: 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
9d30: 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
9d40: 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
9d50: 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
9d60: 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
9d70: 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
9d80: 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
9d90: 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
9da0: 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
9db0: 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
9dc0: 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
9dd0: 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
9de0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
9df0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
9e00: 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
9e10: 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
9e20: 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
9e30: 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
9e40: 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
9e50: 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
9e60: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e  ref="http://www.
9e70: 73 71 6c 69 74 65 2e 6f 72 67 2f 63 76 73 74 72  sqlite.org/cvstr
9e80: 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
9e90: 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
9ea0: 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
9eb0: 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
9ec0: 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
9ed0: 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
9ee0: 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
9ef0: 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
9f00: 61 6e 74 2e 0a 2a 2a 09 0a 2a 2a 20 53 71 6c 69  ant..**..** Sqli
9f10: 74 65 20 69 73 20 72 65 2d 65 6e 74 72 61 6e 74  te is re-entrant
9f20: 2c 20 73 6f 20 74 68 65 20 62 75 73 79 20 68 61  , so the busy ha
9f30: 6e 64 6c 65 72 20 6d 61 79 20 73 74 61 72 74 20  ndler may start 
9f40: 61 20 6e 65 77 20 71 75 65 72 79 2e 20 0a 2a 2a  a new query. .**
9f50: 20 28 49 74 20 69 73 20 6e 6f 74 20 63 6c 65 61   (It is not clea
9f60: 72 20 77 68 79 20 61 6e 79 6f 6e 65 20 77 6f 75  r why anyone wou
9f70: 6c 64 20 65 76 65 72 79 20 77 61 6e 74 20 74 6f  ld every want to
9f80: 20 64 6f 20 74 68 69 73 2c 20 62 75 74 20 69 74   do this, but it
9f90: 0a 2a 2a 20 69 73 20 61 6c 6c 6f 77 65 64 2c 20  .** is allowed, 
9fa0: 69 6e 20 74 68 65 6f 72 79 2e 29 20 20 42 75 74  in theory.)  But
9fb0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
9fc0: 72 20 6d 61 79 20 6e 6f 74 20 63 6c 6f 73 65 20  r may not close 
9fd0: 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
9fe0: 20 20 43 6c 6f 73 69 6e 67 20 74 68 65 20 64 61    Closing the da
9ff0: 74 61 62 61 73 65 20 66 72 6f 6d 20 61 20 62 75  tabase from a bu
a000: 73 79 20 68 61 6e 64 6c 65 72 20 77 69 6c 6c 20  sy handler will 
a010: 64 65 6c 65 74 65 20 0a 2a 2a 20 64 61 74 61 20  delete .** data 
a020: 73 74 72 75 63 74 75 72 65 73 20 6f 75 74 20 66  structures out f
a030: 72 6f 6d 20 75 6e 64 65 72 20 74 68 65 20 65 78  rom under the ex
a040: 65 63 75 74 69 6e 67 20 71 75 65 72 79 20 61 6e  ecuting query an
a050: 64 20 77 69 6c 6c 20 0a 2a 2a 20 70 72 6f 62 61  d will .** proba
a060: 62 6c 79 20 72 65 73 75 6c 74 20 69 6e 20 61 20  bly result in a 
a070: 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
a080: 6c 74 20 6f 72 20 6f 74 68 65 72 20 72 75 6e 74  lt or other runt
a090: 69 6d 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  ime error..**.**
a0a0: 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
a0b0: 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
a0c0: 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
a0d0: 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
a0e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
a0f0: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
a100: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
a110: 65 61 72 73 20 61 6e 79 20 70 72 65 76 69 6f 75  ears any previou
a120: 73 20 6f 6e 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  s one..** Note t
a130: 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
a140: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
a150: 74 28 29 5d 20 77 69 6c 6c 20 61 6c 73 6f 20 73  t()] will also s
a160: 65 74 20 6f 72 20 63 6c 65 61 72 0a 2a 2a 20 74  et or clear.** t
a170: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
a180: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 6f 70 65 72  .**.** When oper
a190: 61 74 69 6e 67 20 69 6e 20 5b 73 71 6c 69 74 65  ating in [sqlite
a1a0: 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
a1b0: 63 61 63 68 65 20 7c 20 73 68 61 72 65 64 20 63  cache | shared c
a1c0: 61 63 68 65 20 6d 6f 64 65 5d 2c 0a 2a 2a 20 6f  ache mode],.** o
a1d0: 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 62 75 73  nly a single bus
a1e0: 79 20 68 61 6e 64 6c 65 72 20 63 61 6e 20 62 65  y handler can be
a1f0: 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
a200: 68 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  h database file.
a210: 0a 2a 2a 20 53 6f 20 69 66 20 74 77 6f 20 64 61  .** So if two da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a230: 6e 73 20 73 68 61 72 65 20 61 20 73 69 6e 67 6c  ns share a singl
a240: 65 20 63 61 63 68 65 2c 20 74 68 65 6e 20 63 68  e cache, then ch
a250: 61 6e 67 69 6e 67 0a 2a 2a 20 74 68 65 20 62 75  anging.** the bu
a260: 73 79 20 68 61 6e 64 6c 65 72 20 6f 6e 20 6f 6e  sy handler on on
a270: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 69 6c  e connection wil
a280: 6c 20 61 6c 73 6f 20 63 68 61 6e 67 65 20 74 68  l also change th
a290: 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
a2a0: 72 20 69 6e 20 74 68 65 20 6f 74 68 65 72 20 63  r in the other c
a2b0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
a2c0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
a2d0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 69 6e 20 74 68  invoked.** in th
a2e0: 65 20 74 68 72 65 61 64 20 74 68 61 74 20 77 61  e thread that wa
a2f0: 73 20 72 75 6e 6e 69 6e 67 20 77 68 65 6e 20 74  s running when t
a300: 68 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 77  he SQLITE_BUSY w
a310: 61 73 20 68 69 74 2e 0a 2a 2f 0a 69 6e 74 20 73  as hit..*/.int s
a320: 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
a330: 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
a340: 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
a350: 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
a360: 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
a370: 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
a380: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
a390: 73 65 74 73 20 61 20 62 75 73 79 20 68 61 6e 64  sets a busy hand
a3a0: 6c 65 72 20 74 68 61 74 20 73 6c 65 65 70 73 20  ler that sleeps 
a3b0: 66 6f 72 20 61 20 77 68 69 6c 65 20 77 68 65 6e  for a while when
a3c0: 20 61 0a 2a 2a 20 74 61 62 6c 65 20 69 73 20 6c   a.** table is l
a3d0: 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
a3e0: 6c 65 72 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  ler will sleep m
a3f0: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
a400: 74 69 6c 20 0a 2a 2a 20 61 74 20 6c 65 61 73 74  til .** at least
a410: 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
a420: 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 20 68  ds of sleeping h
a430: 61 76 65 20 62 65 65 6e 20 64 6f 6e 65 2e 20 20  ave been done.  
a440: 41 66 74 65 72 0a 2a 2a 20 22 6d 73 22 20 6d 69  After.** "ms" mi
a450: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
a460: 65 65 70 69 6e 67 2c 20 74 68 65 20 68 61 6e 64  eeping, the hand
a470: 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
a480: 69 63 68 0a 2a 2a 20 63 61 75 73 65 73 20 5b 73  ich.** causes [s
a490: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
a4a0: 6f 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  o return [SQLITE
a4b0: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
a4c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
a4d0: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
a4e0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
a4f0: 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
a500: 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
a510: 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
a520: 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
a530: 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  andlers..**.** T
a540: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
a550: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
a560: 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
a570: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
a580: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
a590: 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
a5a0: 20 68 61 6e 64 6c 65 72 20 77 61 73 20 64 65 66   handler was def
a5b0: 69 6e 65 64 20 20 0a 2a 2a 20 28 75 73 69 6e 67  ined  .** (using
a5c0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
a5d0: 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
a5e0: 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
a5f0: 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
a600: 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
a610: 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
a620: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
a630: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
a640: 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
a650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a660: 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
a670: 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
a680: 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
a690: 54 68 69 73 20 6e 65 78 74 20 72 6f 75 74 69 6e  This next routin
a6a0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
a6b0: 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e  ce wrapper aroun
a6c0: 64 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  d [sqlite3_exec(
a6d0: 29 5d 2e 0a 2a 2a 20 49 6e 73 74 65 61 64 20 6f  )]..** Instead o
a6e0: 66 20 69 6e 76 6f 6b 69 6e 67 20 61 20 75 73 65  f invoking a use
a6f0: 72 2d 73 75 70 70 6c 69 65 64 20 63 61 6c 6c 62  r-supplied callb
a700: 61 63 6b 20 66 6f 72 20 65 61 63 68 20 72 6f 77  ack for each row
a710: 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   of the.** resul
a720: 74 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  t, this routine 
a730: 72 65 6d 65 6d 62 65 72 73 20 65 61 63 68 20 72  remembers each r
a740: 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
a750: 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62   in memory.** ob
a760: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
a770: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
a780: 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 6c 6c  then returns all
a790: 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 61   of the result a
a7a0: 66 74 65 72 20 74 68 65 0a 2a 2a 20 71 75 65 72  fter the.** quer
a7b0: 79 20 68 61 73 20 66 69 6e 69 73 68 65 64 2e 20  y has finished. 
a7c0: 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
a7d0: 6d 70 6c 65 2c 20 73 75 70 70 6f 73 65 20 74 68  mple, suppose th
a7e0: 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 77  e query result w
a7f0: 68 65 72 65 20 74 68 69 73 20 74 61 62 6c 65 3a  here this table:
a800: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
a810: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
a820: 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
a830: 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
a840: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
a850: 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
a860: 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
a870: 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
a880: 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
a890: 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
a8a0: 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
a8b0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
a8c0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
a8d0: 61 72 67 75 6d 65 6e 74 20 77 65 72 65 20 26 61  argument were &a
a8e0: 7a 52 65 73 75 6c 74 20 74 68 65 6e 20 61 66 74  zResult then aft
a8f0: 65 72 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  er the function 
a900: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 7a 52 65 73  returns.** azRes
a910: 75 6c 74 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ult will contain
a920: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 64   the following d
a930: 61 74 61 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ata:.**.** <bloc
a940: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
a950: 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
a960: 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
a970: 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
a980: 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
a990: 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
a9a0: 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
a9b0: 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
a9c0: 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
a9d0: 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
a9e0: 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
a9f0: 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
aa00: 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
aa10: 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
aa20: 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
aa30: 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
aa40: 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
aa50: 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
aa60: 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
aa70: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
aa80: 0a 2a 2a 20 4e 6f 74 69 63 65 20 74 68 61 74 20  .** Notice that 
aa90: 74 68 65 72 65 20 69 73 20 61 6e 20 65 78 74 72  there is an extr
aaa0: 61 20 72 6f 77 20 6f 66 20 64 61 74 61 20 63 6f  a row of data co
aab0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c  ntaining the col
aac0: 75 6d 6e 0a 2a 2a 20 68 65 61 64 65 72 73 2e 20  umn.** headers. 
aad0: 20 42 75 74 20 74 68 65 20 2a 6e 72 6f 77 20 72   But the *nrow r
aae0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 20 73  eturn value is s
aaf0: 74 69 6c 6c 20 33 2e 20 20 2a 6e 63 6f 6c 75 6d  till 3.  *ncolum
ab00: 6e 20 69 73 0a 2a 2a 20 73 65 74 20 74 6f 20 32  n is.** set to 2
ab10: 2e 20 20 49 6e 20 67 65 6e 65 72 61 6c 2c 20 74  .  In general, t
ab20: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
ab30: 75 65 73 20 69 6e 73 65 72 74 65 64 20 69 6e 74  ues inserted int
ab40: 6f 20 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 77 69  o azResult.** wi
ab50: 6c 6c 20 62 65 20 28 28 2a 6e 72 6f 77 29 20 2b  ll be ((*nrow) +
ab60: 20 31 29 2a 28 2a 6e 63 6f 6c 75 6d 6e 29 2e 0a   1)*(*ncolumn)..
ab70: 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
ab80: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
ab90: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
aba0: 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20  ing the result, 
abb0: 69 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 61  it should .** pa
abc0: 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 64 61  ss the result da
abd0: 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ta pointer to sq
abe0: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
abf0: 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 0a  () in order to .
ac00: 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
ac10: 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
ac20: 61 6c 6c 6f 63 2d 65 64 2e 20 20 42 65 63 61 75  alloc-ed.  Becau
ac30: 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
ac40: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  e .** [sqlite3_m
ac50: 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
ac60: 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
ac70: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
ac80: 74 72 79 20 74 6f 20 63 61 6c 6c 20 0a 2a 2a 20  try to call .** 
ac90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
aca0: 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
acb0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
acc0: 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
acd0: 74 6f 20 72 65 6c 65 61 73 65 20 0a 2a 2a 20 74  to release .** t
ace0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
acf0: 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
ad00: 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20  *.** The return 
ad10: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f  value of this ro
ad20: 75 74 69 6e 65 20 69 73 20 74 68 65 20 73 61 6d  utine is the sam
ad30: 65 20 61 73 20 66 72 6f 6d 20 5b 73 71 6c 69 74  e as from [sqlit
ad40: 65 33 5f 65 78 65 63 28 29 5d 2e 0a 2a 2f 0a 69  e3_exec()]..*/.i
ad50: 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
ad60: 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 2a  able(.  sqlite3*
ad70: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
ad80: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
ad90: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
ada0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 2f  ar *sql,       /
adb0: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 78 65 63  * SQL to be exec
adc0: 75 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  uted */.  char *
add0: 2a 2a 72 65 73 75 6c 74 70 2c 20 20 20 20 20 20  **resultp,      
ade0: 20 2f 2a 20 52 65 73 75 6c 74 20 77 72 69 74 74   /* Result writt
adf0: 65 6e 20 74 6f 20 61 20 63 68 61 72 20 2a 5b 5d  en to a char *[]
ae00: 20 20 74 68 61 74 20 74 68 69 73 20 70 6f 69 6e    that this poin
ae10: 74 73 20 74 6f 20 2a 2f 0a 20 20 69 6e 74 20 2a  ts to */.  int *
ae20: 6e 72 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nrow,           
ae30: 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
ae40: 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
ae50: 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
ae60: 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20   *ncolumn,      
ae70: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
ae80: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
ae90: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
aea0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
aeb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
aec0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
aed0: 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
aee0: 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
aef0: 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
af00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
af10: 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
af20: 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
af30: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
af40: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
af50: 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
af60: 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
af70: 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
af80: 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
af90: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
afa0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
afb0: 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
afc0: 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
afd0: 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
afe0: 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
aff0: 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
b000: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
b010: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
b020: 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
b030: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
b040: 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
b050: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
b060: 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
b070: 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20  _free()].  Both 
b080: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
b090: 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
b0a0: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
b0b0: 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
b0c0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
b0d0: 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
b0e0: 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
b0f0: 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
b100: 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
b110: 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
b120: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
b130: 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
b140: 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
b150: 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
b160: 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
b170: 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
b180: 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
b190: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
b1a0: 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
b1b0: 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
b1c0: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
b1d0: 65 74 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  eter.  Note that
b1e0: 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
b1f0: 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
b200: 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
b210: 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
b220: 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20  ntf().  This is 
b230: 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
b240: 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
b250: 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
b260: 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
b270: 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
b280: 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74  patibility.  Not
b290: 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
b2a0: 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
b2b0: 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
b2c0: 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
b2d0: 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
b2e0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
b2f0: 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
b300: 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
b310: 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61  he buffer.  We a
b320: 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
b330: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
b340: 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
b350: 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
b360: 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
b370: 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
b380: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
b390: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
b3a0: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
b3b0: 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
b3c0: 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
b3d0: 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
b3e0: 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
b3f0: 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
b400: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
b410: 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
b420: 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
b430: 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
b440: 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
b450: 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68  -terminated.  Th
b460: 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
b470: 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
b480: 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
b490: 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
b4a0: 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
b4b0: 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
b4c0: 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
b4d0: 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
b4e0: 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
b4f0: 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
b500: 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
b510: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
b520: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
b530: 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
b540: 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
b550: 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
b560: 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
b570: 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
b580: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
b590: 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
b5a0: 73 75 61 6c 20 70 72 69 6e 74 66 20 66 6f 72 6d  sual printf form
b5b0: 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
b5c0: 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
b5d0: 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
b5e0: 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
b5f0: 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
b600: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f  ..**.** The %q o
b610: 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
b620: 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
b630: 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
b640: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
b650: 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
b660: 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
b670: 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
b680: 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
b690: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
b6a0: 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
b6b0: 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
b6c0: 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79  ing literal.  By
b6d0: 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
b6e0: 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
b6f0: 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
b700: 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
b710: 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
b720: 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
b730: 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
b740: 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 73  * For example, s
b750: 6f 20 73 6f 6d 65 20 73 74 72 69 6e 67 20 76 61  o some string va
b760: 72 69 61 62 6c 65 20 63 6f 6e 74 61 69 6e 73 20  riable contains 
b770: 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
b780: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
b790: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
b7a0: 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
b7b0: 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
b7c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
b7d0: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
b7e0: 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
b7f0: 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
b800: 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
b810: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
b820: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
b830: 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
b840: 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
b850: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
b860: 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
b870: 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
b880: 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
b890: 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
b8a0: 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
b8b0: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
b8c0: 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
b8d0: 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
b8e0: 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
b8f0: 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
b900: 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
b910: 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
b920: 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
b930: 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
b940: 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
b950: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
b960: 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
b970: 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
b980: 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
b990: 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
b9a0: 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
b9b0: 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
b9c0: 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
b9d0: 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
b9e0: 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
b9f0: 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
ba00: 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
ba10: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
ba20: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
ba30: 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
ba40: 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
ba50: 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
ba60: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
ba70: 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
ba80: 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
ba90: 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
baa0: 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
bab0: 61 6c 20 72 75 6c 65 20 79 6f 75 0a 2a 2a 20 73  al rule you.** s
bac0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 73 65  hould always use
bad0: 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
bae0: 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
baf0: 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
bb00: 69 6e 67 20 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e  ing .** literal.
bb10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70  .**.** The %Q op
bb20: 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
bb30: 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
bb40: 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
bb50: 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
bb60: 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
bb70: 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
bb80: 20 4f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   Or if the param
bb90: 65 74 65 72 20 69 6e 20 74 68 65 20 61 72 67 75  eter in the argu
bba0: 6d 65 6e 74 0a 2a 2a 20 6c 69 73 74 20 69 73 20  ment.** list is 
bbb0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
bbc0: 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
bbd0: 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
bbe0: 77 69 74 68 6f 75 74 20 73 69 6e 67 6c 65 0a 2a  without single.*
bbf0: 2a 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61  * quotes) in pla
bc00: 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74  ce of the %Q opt
bc10: 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ion.  So, for ex
bc20: 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
bc30: 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
bc40: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
bc50: 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
bc60: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
bc70: 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
bc80: 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
bc90: 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
bca0: 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
bcb0: 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
bcc0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
bcd0: 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
bce0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
bcf0: 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
bd00: 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
bd10: 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
bd20: 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
bd30: 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
bd40: 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
bd50: 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
bd60: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
bd70: 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
bd80: 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
bd90: 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25   exactly like "%
bda0: 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  s" with the.** a
bdb0: 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
bdc0: 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
bdd0: 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
bde0: 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
bdf0: 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
be00: 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
be10: 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
be20: 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2f 0a 63 68  ut string..*/.ch
be30: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
be40: 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
be50: 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
be60: 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
be70: 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
be80: 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
be90: 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
bea0: 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
beb0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
bec0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
bed0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
bee0: 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
bef0: 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
bf00: 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
bf10: 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
bf20: 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
bf30: 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
bf40: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 28 53 65  ation needs. (Se
bf50: 65 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20  e the exception 
bf60: 62 65 6c 6f 77 2e 29 0a 2a 2a 0a 2a 2a 20 54 68  below.).**.** Th
bf70: 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
bf80: 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74  entation.** of t
bf90: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bfa0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75  tion subsystem u
bfb0: 73 65 73 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  ses the malloc()
bfc0: 2c 20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 61  , realloc().** a
bfd0: 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64  nd free() provid
bfe0: 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61  ed by the standa
bff0: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 48  rd C library.  H
c000: 6f 77 65 76 65 72 2c 20 69 66 20 0a 2a 2a 20 53  owever, if .** S
c010: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
c020: 64 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f  d with the follo
c030: 77 69 6e 67 20 43 20 70 72 65 70 72 6f 63 65 73  wing C preproces
c040: 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 0a 2a 2a 20  sor macro.**.** 
c050: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 20 53 51 4c  <blockquote> SQL
c060: 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
c070: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 3c 2f 62 6c 6f  <i>NNN</i> </blo
c080: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77  ckquote>.**.** w
c090: 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  here <i>NNN</i> 
c0a0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  is an integer, t
c0b0: 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
c0c0: 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 61 72  e a static.** ar
c0d0: 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ray of at least 
c0e0: 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
c0f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
c100: 20 74 68 61 74 20 61 72 72 61 79 0a 2a 2a 20 66   that array.** f
c110: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
c120: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
c130: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
c140: 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
c150: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
c160: 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
c170: 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
c180: 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
c190: 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
c1a0: 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
c1b0: 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
c1c0: 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
c1d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
c1e0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
c1f0: 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
c200: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
c210: 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
c220: 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
c230: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
c240: 74 6f 72 73 20 63 61 6e 20 62 65 0a 2a 2a 20 75  tors can be.** u
c250: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 45 78  sed..**.** <b>Ex
c260: 63 65 70 74 69 6f 6e 3a 3c 2f 62 3e 20 54 68 65  ception:</b> The
c270: 20 77 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   windows OS inte
c280: 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
c290: 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
c2a0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
c2b0: 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
c2c0: 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
c2d0: 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
c2e0: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
c2f0: 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
c300: 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
c310: 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
c320: 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
c330: 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
c340: 77 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  windows.** insta
c350: 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
c360: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
c370: 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
c380: 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
c390: 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
c3a0: 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
c3b0: 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
c3c0: 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
c3d0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
c3e0: 45 4d 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  EM]..*/.void *sq
c3f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
c400: 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
c410: 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
c420: 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
c430: 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
c440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c450: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
c460: 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
c470: 2a 2a 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** In addition t
c480: 6f 20 74 68 65 20 62 61 73 69 63 20 74 68 72 65  o the basic thre
c490: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  e allocation rou
c4a0: 74 69 6e 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  tines .** [sqlit
c4b0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
c4c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
c4d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
c4e0: 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 74 68 65 20  lloc()],.** the 
c4f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c500: 6e 20 73 75 62 73 79 73 74 65 6d 20 69 6e 63 6c  n subsystem incl
c510: 75 64 65 64 20 77 69 74 68 20 74 68 65 20 53 51  uded with the SQ
c520: 4c 69 74 65 0a 2a 2a 20 73 6f 75 72 63 65 73 20  Lite.** sources 
c530: 70 72 6f 76 69 64 65 73 20 74 68 65 20 69 6e 74  provides the int
c540: 65 72 66 61 63 65 73 20 73 68 6f 77 6e 20 62 65  erfaces shown be
c550: 6c 6f 77 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  low..**.** The f
c560: 69 72 73 74 20 6f 66 20 74 68 65 73 65 20 74 77  irst of these tw
c570: 6f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  o routines retur
c580: 6e 73 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ns the amount of
c590: 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 63 75 72 72   memory .** curr
c5a0: 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
c5b0: 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
c5c0: 6e 6f 74 20 66 72 65 65 64 29 2e 20 20 54 68 65  not freed).  The
c5d0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 74 75 72   second.** retur
c5e0: 6e 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 69  ns the largest i
c5f0: 6e 73 74 61 6e 74 61 6e 65 6f 75 73 20 61 6d 6f  nstantaneous amo
c600: 75 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e 64 69  unt of outstandi
c610: 6e 67 0a 2a 2a 20 6d 65 6d 6f 72 79 2e 20 20 54  ng.** memory.  T
c620: 68 65 20 68 69 67 68 77 61 74 65 72 20 6d 61 72  he highwater mar
c630: 6b 20 69 73 20 72 65 73 65 74 20 69 66 20 74 68  k is reset if th
c640: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  e argument is.**
c650: 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   true..**.** The
c660: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
c670: 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 69  may or may not i
c680: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
c690: 6e 0a 2a 2a 20 6f 76 65 72 68 65 61 64 2c 20 64  n.** overhead, d
c6a0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
c6b0: 68 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  h built-in memor
c6c0: 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20 69  y allocator.** i
c6d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
c6e0: 20 75 73 65 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65   used..*/.sqlite
c6f0: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
c700: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
c710: 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
c720: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
c730: 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
c740: 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
c750: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
c760: 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
c770: 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
c780: 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  ***.** This rout
c790: 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
c7a0: 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
c7b0: 61 63 6b 20 77 69 74 68 20 74 68 65 20 53 51 4c  ack with the SQL
c7c0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 0a 2a  ite library.  .*
c7d0: 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
c7e0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
c7f0: 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
c800: 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
c810: 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
c820: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
c830: 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
c840: 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
c850: 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
c860: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
c870: 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
c880: 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
c890: 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
c8a0: 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
c8b0: 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
c8c0: 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
c8d0: 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
c8e0: 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
c8f0: 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
c900: 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
c910: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
c920: 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
c930: 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
c940: 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
c950: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
c960: 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
c970: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c980: 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
c990: 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
c9a0: 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
c9b0: 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
c9c0: 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
c9d0: 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
c9e0: 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
c9f0: 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
ca00: 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
ca10: 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
ca20: 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
ca30: 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
ca40: 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
ca50: 20 65 72 72 6f 72 2e 20 20 0a 2a 2a 0a 2a 2a 20   error.  .**.** 
ca60: 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  Depending on the
ca70: 20 61 63 74 69 6f 6e 2c 20 74 68 65 20 5b 53 51   action, the [SQ
ca80: 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64  LITE_IGNORE] and
ca90: 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 72   [SQLITE_DENY] r
caa0: 65 74 75 72 6e 0a 2a 2a 20 63 6f 64 65 73 20 6d  eturn.** codes m
cab0: 69 67 68 74 20 6d 65 61 6e 20 73 6f 6d 65 74 68  ight mean someth
cac0: 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 6f 72  ing different or
cad0: 20 74 68 65 79 20 6d 69 67 68 74 20 6d 65 61 6e   they might mean
cae0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 68 69   the same.** thi
caf0: 6e 67 2e 20 20 49 66 20 74 68 65 20 61 63 74 69  ng.  If the acti
cb00: 6f 6e 20 69 73 2c 20 66 6f 72 20 65 78 61 6d 70  on is, for examp
cb10: 6c 65 2c 20 74 6f 20 70 65 72 66 6f 72 6d 20 61  le, to perform a
cb20: 20 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e   delete opertion
cb30: 2c 0a 2a 2a 20 74 68 65 6e 20 5b 53 51 4c 49 54  ,.** then [SQLIT
cb40: 45 5f 49 47 4e 4f 52 45 5d 20 61 6e 64 20 5b 53  E_IGNORE] and [S
cb50: 51 4c 49 54 45 5f 44 45 4e 59 5d 20 62 6f 74 68  QLITE_DENY] both
cb60: 20 63 61 75 73 65 20 74 68 65 20 73 74 61 74 65   cause the state
cb70: 6d 65 6e 74 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  ment compilation
cb80: 0a 2a 2a 20 74 6f 20 66 61 69 6c 20 77 69 74 68  .** to fail with
cb90: 20 61 6e 20 65 72 72 6f 72 2e 20 20 42 75 74 20   an error.  But 
cba0: 69 66 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  if the action is
cbb0: 20 74 6f 20 72 65 61 64 20 61 20 73 70 65 63 69   to read a speci
cbc0: 66 69 63 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 66 72  fic column.** fr
cbd0: 6f 6d 20 61 20 73 70 65 63 69 66 69 63 20 74 61  om a specific ta
cbe0: 62 6c 65 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ble, then [SQLIT
cbf0: 45 5f 44 45 4e 59 5d 20 77 69 6c 6c 20 63 61 75  E_DENY] will cau
cc00: 73 65 20 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a  se the entire.**
cc10: 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 66 61   statement to fa
cc20: 69 6c 20 62 75 74 20 5b 53 51 4c 49 54 45 5f 49  il but [SQLITE_I
cc30: 47 4e 4f 52 45 5d 20 77 69 6c 6c 20 63 61 75 73  GNORE] will caus
cc40: 65 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74  e a NULL value t
cc50: 6f 20 62 65 0a 2a 2a 20 72 65 61 64 20 69 6e 73  o be.** read ins
cc60: 74 65 61 64 20 6f 66 20 74 68 65 20 61 63 74 75  tead of the actu
cc70: 61 6c 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  al column value.
cc80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
cc90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
cca0: 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
ccb0: 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
ccc0: 6f 66 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  of.** the third 
ccd0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
cce0: 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
ccf0: 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
cd00: 61 63 65 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ace..** The seco
cd10: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
cd20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
cd30: 61 6e 20 69 6e 74 65 67 65 72 20 0a 2a 2a 20 5b  an integer .** [
cd40: 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
cd50: 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
cd60: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
cd70: 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
cd80: 2a 2a 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  ** to be authori
cd90: 7a 65 64 2e 20 20 54 68 65 20 61 76 61 69 6c 61  zed.  The availa
cda0: 62 6c 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ble action codes
cdb0: 20 61 72 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   are.** [SQLITE_
cdc0: 43 4f 50 59 20 7c 20 64 6f 63 75 6d 65 6e 74 65  COPY | documente
cdd0: 64 20 73 65 70 61 72 61 74 65 6c 79 5d 2e 20 20  d separately].  
cde0: 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
cdf0: 68 20 73 69 78 74 68 0a 2a 2a 20 70 61 72 61 6d  h sixth.** param
ce00: 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
ce10: 6c 62 61 63 6b 20 61 72 65 20 73 74 72 69 6e 67  lback are string
ce20: 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
ce30: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
ce40: 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
ce50: 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
ce60: 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
ce70: 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
ce80: 73 65 64 20 77 68 65 6e 20 70 72 65 70 61 72 69  sed when prepari
ce90: 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
cea0: 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
ceb0: 74 65 64 0a 2a 2a 20 73 6f 75 72 63 65 2c 20 74  ted.** source, t
cec0: 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
ced0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
cee0: 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
cef0: 63 63 65 73 73 20 64 61 74 61 0a 2a 2a 20 74 68  ccess data.** th
cf00: 61 74 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  at they are not 
cf10: 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
cf20: 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
cf30: 6e 6f 74 20 74 72 79 20 74 6f 0a 2a 2a 20 65 78  not try to.** ex
cf40: 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
cf50: 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
cf60: 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
cf70: 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
cf80: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
cf90: 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
cfa0: 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
cfb0: 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
cfc0: 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
cfd0: 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
cfe0: 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
cff0: 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
d000: 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
d010: 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
d020: 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
d030: 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
d040: 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
d050: 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
d060: 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
d070: 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
d080: 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
d090: 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 70  d SQL is being p
d0a0: 72 65 70 61 72 65 64 20 74 68 61 74 20 64 69 73  repared that dis
d0b0: 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
d0c0: 67 0a 2a 2a 20 65 78 63 65 70 74 20 53 45 4c 45  g.** except SELE
d0d0: 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  CT statements.  
d0e0: 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69  .**.** Only a si
d0f0: 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
d100: 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
d110: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
d120: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
d130: 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
d140: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
d150: 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
d160: 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
d170: 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 41 20 4e  vious call.  A N
d180: 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
d190: 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
d1a0: 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
d1b0: 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
d1c0: 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
d1d0: 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55  authorizer is NU
d1e0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  LL..**.** Note t
d1f0: 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
d200: 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
d210: 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
d220: 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
d230: 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
d240: 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
d250: 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
d260: 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
d270: 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
d280: 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
d290: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
d2a0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
d2b0: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
d2c0: 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
d2d0: 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
d2e0: 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
d2f0: 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
d300: 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
d310: 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
d320: 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
d330: 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
d340: 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
d350: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
d360: 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
d370: 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
d380: 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
d390: 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
d3a0: 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
d3b0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
d3c0: 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
d3d0: 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
d3e0: 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
d3f0: 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
d400: 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
d410: 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
d420: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
d430: 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
d440: 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
d450: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
d460: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
d470: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
d480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
d490: 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
d4a0: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
d4b0: 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
d4c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d4d0: 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
d4e0: 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
d4f0: 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
d500: 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
d510: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
d520: 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
d530: 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
d540: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
d550: 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
d560: 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
d570: 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
d580: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
d590: 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
d5a0: 75 74 68 6f 72 69 7a 65 72 20 63 65 72 74 61 69  uthorizer certai
d5b0: 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
d5c0: 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
d5d0: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
d5e0: 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
d5f0: 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
d600: 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
d610: 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
d620: 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
d630: 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
d640: 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
d650: 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
d660: 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
d670: 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
d680: 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
d690: 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
d6a0: 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
d6b0: 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
d6c0: 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
d6d0: 65 20 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  e .** authorized
d6e0: 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
d6f0: 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
d700: 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
d710: 6f 6e 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  on callback.** f
d720: 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
d730: 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
d740: 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
d750: 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
d760: 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
d770: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
d780: 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74  rameter.  The 5t
d790: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
d7a0: 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
d7b0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
d7c0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
d7d0: 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
d7e0: 74 65 6d 70 22 2c 20 0a 2a 2a 20 65 74 63 2e 29  temp", .** etc.)
d7f0: 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20   if applicable. 
d800: 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
d810: 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
d820: 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
d830: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
d840: 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
d850: 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
d860: 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
d870: 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
d880: 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
d890: 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
d8a0: 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
d8b0: 69 72 65 63 74 6c 79 20 66 72 6f 6d 20 0a 2a 2a  irectly from .**
d8c0: 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
d8d0: 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
d8e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d8f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
d900: 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
d910: 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
d920: 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
d930: 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
d940: 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
d950: 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
d960: 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
d970: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
d980: 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
d990: 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
d9a0: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
d9b0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
d9c0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
d9d0: 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
d9e0: 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
d9f0: 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
da00: 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
da10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
da20: 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
da30: 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
da40: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
da50: 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
da60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
da70: 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
da80: 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
da90: 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
daa0: 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
dab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dac0: 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
dad0: 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
dae0: 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
daf0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
db00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
db10: 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
db20: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
db30: 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
db40: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
db50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
db60: 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
db70: 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
db80: 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
db90: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
dba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
dbb0: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
dbc0: 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
dbd0: 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
dbe0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
dbf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
dc00: 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
dc10: 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
dc20: 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
dc30: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
dc40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
dc50: 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
dc60: 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
dc70: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
dc80: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
dc90: 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
dca0: 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
dcb0: 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
dcc0: 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
dcd0: 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
dce0: 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
dcf0: 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
dd00: 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
dd10: 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
dd20: 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
dd30: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
dd40: 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
dd50: 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
dd60: 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
dd70: 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
dd80: 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
dd90: 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
dda0: 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
ddb0: 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
ddc0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
ddd0: 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
dde0: 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
ddf0: 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
de00: 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
de10: 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
de20: 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
de30: 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
de40: 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
de50: 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
de60: 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
de70: 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
de80: 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
de90: 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
dea0: 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
deb0: 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
dec0: 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
ded0: 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
dee0: 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
def0: 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
df00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
df10: 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
df20: 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
df30: 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
df40: 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
df50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
df60: 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
df70: 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
df80: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
df90: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
dfa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dfb0: 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
dfc0: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55        22   /* NU
dfd0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
dfe0: 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
dff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e000: 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
e010: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
e020: 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
e030: 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
e040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e050: 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
e060: 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
e070: 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
e080: 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
e090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
e0a0: 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
e0b0: 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
e0c0: 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
e0d0: 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
e0e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
e0f0: 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
e100: 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
e110: 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
e120: 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
e130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
e140: 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
e150: 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
e160: 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
e170: 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
e180: 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
e190: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
e1a0: 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
e1b0: 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
e1c0: 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
e1d0: 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
e1e0: 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
e1f0: 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
e200: 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
e210: 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
e220: 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
e230: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
e240: 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
e250: 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
e260: 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
e270: 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
e280: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
e290: 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61    /* Function Na
e2a0: 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
e2b0: 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
e2c0: 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
e2d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
e2e0: 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
e2f0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e300: 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
e310: 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
e320: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
e330: 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
e340: 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
e350: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
e360: 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
e370: 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
e380: 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
e390: 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
e3a0: 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 63 61  ments..** The ca
e3b0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
e3c0: 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
e3d0: 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
e3e0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 74 20 74   invoked.** at t
e3f0: 68 65 20 66 69 72 73 74 20 5b 73 71 6c 69 74 65  he first [sqlite
e400: 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 74 68  3_step()] for th
e410: 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
e420: 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
e430: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  ..** The callbac
e440: 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
e450: 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
e460: 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
e470: 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
e480: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
e490: 69 6e 69 73 68 65 73 20 61 6e 64 20 69 6e 63 6c  inishes and incl
e4a0: 75 64 65 73 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  udes.** informat
e4b0: 69 6f 6e 20 6f 6e 20 68 6f 77 20 6c 6f 6e 67 20  ion on how long 
e4c0: 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 72  that statement r
e4d0: 61 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  an..**.** The sq
e4e0: 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
e4f0: 41 50 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79  API is currently
e500: 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
e510: 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20  rimental and.** 
e520: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
e530: 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ange..*/.void *s
e540: 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
e550: 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
e560: 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
e570: 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
e580: 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70  .void *sqlite3_p
e590: 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
e5a0: 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
e5b0: 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
e5c0: 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
e5d0: 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
e5e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e5f0: 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
e600: 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 54  allbacks.**.** T
e610: 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
e620: 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
e630: 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
e640: 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
e650: 63 6b 20 2d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ck - that.** is 
e660: 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
e670: 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
e680: 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
e690: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
e6a0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
e6b0: 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
e6c0: 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
e6d0: 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
e6e0: 73 65 20 66 6f 72 20 74 68 69 73 20 0a 2a 2a 20  se for this .** 
e6f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
e700: 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
e710: 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
e720: 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 54  e query..**.** T
e730: 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
e740: 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
e750: 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
e760: 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
e770: 20 6f 70 63 6f 64 65 73 2c 0a 2a 2a 20 77 68 65   opcodes,.** whe
e780: 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
e790: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
e7a0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  his function. Th
e7b0: 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
e7c0: 61 63 6b 0a 2a 2a 20 69 74 73 65 6c 66 20 69 73  ack.** itself is
e7d0: 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
e7e0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
e7f0: 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  t to this functi
e800: 6f 6e 2e 20 54 68 65 20 66 6f 75 72 74 68 0a 2a  on. The fourth.*
e810: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
e820: 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
e830: 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
e840: 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
e850: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
e860: 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
e870: 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
e880: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 61  d..**.** If a ca
e890: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ll to [sqlite3_e
e8a0: 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
e8b0: 5f 73 74 65 70 28 29 5d 2c 20 6f 72 20 5b 73 71  _step()], or [sq
e8c0: 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
e8d0: 29 5d 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  )].** results in
e8e0: 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
e8f0: 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
e900: 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70  uted, then the p
e910: 72 6f 67 72 65 73 73 20 0a 2a 2a 20 63 61 6c 6c  rogress .** call
e920: 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
e930: 76 6f 6b 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 4f 6e  voked..** .** On
e940: 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
e950: 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 66 75  ress callback fu
e960: 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
e970: 67 69 73 74 65 72 65 64 20 66 6f 72 20 65 61 63  gistered for eac
e980: 68 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61 62 61  h.** open databa
e990: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
e9a0: 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 73 71  Every call to sq
e9b0: 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
e9c0: 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 6f 76 65 72  andler().** over
e9d0: 77 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c  writes the resul
e9e0: 74 73 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  ts of the previo
e9f0: 75 73 20 63 61 6c 6c 2e 0a 2a 2a 20 54 6f 20 72  us call..** To r
ea00: 65 6d 6f 76 65 20 74 68 65 20 70 72 6f 67 72 65  emove the progre
ea10: 73 73 20 63 61 6c 6c 62 61 63 6b 20 61 6c 74 6f  ss callback alto
ea20: 67 65 74 68 65 72 2c 20 70 61 73 73 20 4e 55 4c  gether, pass NUL
ea30: 4c 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  L as the third.*
ea40: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  * argument to th
ea50: 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
ea60: 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
ea70: 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
ea80: 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
ea90: 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 20  er than 0, then 
eaa0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
eab0: 71 75 65 72 79 20 69 73 20 69 6d 6d 65 64 69 61  query is immedia
eac0: 74 65 6c 79 20 74 65 72 6d 69 6e 61 74 65 64 20  tely terminated 
ead0: 61 6e 64 20 61 6e 79 20 64 61 74 61 62 61 73 65  and any database
eae0: 20 63 68 61 6e 67 65 73 20 72 6f 6c 6c 65 64 20   changes rolled 
eaf0: 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 63 6f 6e  back..** The con
eb00: 74 61 69 6e 69 6e 67 20 5b 73 71 6c 69 74 65 33  taining [sqlite3
eb10: 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
eb20: 65 33 5f 73 74 65 70 28 29 5d 2c 20 6f 72 0a 2a  e3_step()], or.*
eb30: 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
eb40: 61 62 6c 65 28 29 5d 20 63 61 6c 6c 20 72 65 74  able()] call ret
eb50: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4e 54 45  urns SQLITE_INTE
eb60: 52 52 55 50 54 2e 20 20 20 54 68 69 73 20 66 65  RRUPT.   This fe
eb70: 61 74 75 72 65 0a 2a 2a 20 63 61 6e 20 62 65 20  ature.** can be 
eb80: 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
eb90: 65 2c 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  e, to implement 
eba0: 74 68 65 20 22 43 61 6e 63 65 6c 22 20 62 75 74  the "Cancel" but
ebb0: 74 6f 6e 20 6f 6e 20 61 0a 2a 2a 20 70 72 6f 67  ton on a.** prog
ebc0: 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 20  ress dialog box 
ebd0: 69 6e 20 61 20 47 55 49 2e 0a 2a 2f 0a 76 6f 69  in a GUI..*/.voi
ebe0: 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
ebf0: 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
ec00: 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
ec10: 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
ec20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ec30: 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
ec40: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
ec50: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 4f 70 65 6e 20 74  ion.**.** Open t
ec60: 68 65 20 73 71 6c 69 74 65 20 64 61 74 61 62 61  he sqlite databa
ec70: 73 65 20 66 69 6c 65 20 22 66 69 6c 65 6e 61 6d  se file "filenam
ec80: 65 22 2e 20 20 54 68 65 20 22 66 69 6c 65 6e 61  e".  The "filena
ec90: 6d 65 22 20 69 73 20 55 54 46 2d 38 0a 2a 2a 20  me" is UTF-8.** 
eca0: 65 6e 63 6f 64 65 64 20 66 6f 72 20 5b 73 71 6c  encoded for [sql
ecb0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
ecc0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
ecd0: 32 28 29 5d 20 61 6e 64 20 55 54 46 2d 31 36 20  2()] and UTF-16 
ece0: 65 6e 63 6f 64 65 64 0a 2a 2a 20 69 6e 20 74 68  encoded.** in th
ecf0: 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
ed00: 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  der for [sqlite3
ed10: 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 41  _open16()]..** A
ed20: 6e 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61 6e  n [sqlite3*] han
ed30: 64 6c 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  dle is returned 
ed40: 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 0a 2a  in *ppDb, even.*
ed50: 2a 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  * if an error oc
ed60: 63 75 72 73 2e 20 49 66 20 74 68 65 20 64 61 74  curs. If the dat
ed70: 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
ed80: 28 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  (or created) suc
ed90: 63 65 73 73 66 75 6c 6c 79 2c 0a 2a 2a 20 74 68  cessfully,.** th
eda0: 65 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  en [SQLITE_OK] i
edb0: 73 20 72 65 74 75 72 6e 65 64 2e 20 4f 74 68 65  s returned. Othe
edc0: 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 63  rwise an error c
edd0: 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ode is returned.
ede0: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
edf0: 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
ee00: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
ee10: 29 5d 20 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  )]  routines can
ee20: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
ee30: 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
ee40: 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
ee50: 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
ee60: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  or..**.** The de
ee70: 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
ee80: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
ee90: 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
eea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
eeb0: 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
eec0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 63  _open_v2()] is c
eed0: 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
eee0: 2d 31 36 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  -16 if [sqlite3_
eef0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ef00: 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
ef10: 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
ef20: 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
ef30: 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
ef40: 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 0a  rces associated.
ef50: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
ef60: 69 74 65 33 2a 5d 20 68 61 6e 64 6c 65 20 73 68  ite3*] handle sh
ef70: 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
ef80: 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
ef90: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6c  o.** [sqlite3_cl
efa0: 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
efb0: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
efc0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
efd0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
efe0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 6f  ()] interface wo
eff0: 72 6b 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  rks like [sqlite
f000: 33 5f 6f 70 65 6e 28 29 5d 20 65 78 63 65 70 74  3_open()] except
f010: 20 74 68 61 74 0a 2a 2a 20 70 72 6f 76 69 64 65   that.** provide
f020: 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
f030: 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
f040: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
f050: 6f 6c 20 6f 76 65 72 20 74 68 65 0a 2a 2a 20 6e  ol over the.** n
f060: 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
f070: 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61  ection.  The fla
f080: 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e  gs parameter can
f090: 20 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a   be one of:.**.*
f0a0: 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ol>.** <li>  
f0b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
f0c0: 44 4f 4e 4c 59 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  DONLY].** <li>  
f0d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
f0e0: 44 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  DWRITE].** <li> 
f0f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
f100: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
f110: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 0a  TE_OPEN_CREATE].
f120: 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ol>.**.** T
f130: 68 65 20 66 69 72 73 74 20 76 61 6c 75 65 20 6f  he first value o
f140: 70 65 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  pens the databas
f150: 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 49 66  e read-only.  If
f160: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
f170: 65 73 0a 2a 2a 20 6e 6f 74 20 70 72 65 76 69 6f  es.** not previo
f180: 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
f190: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
f1a0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 6f 70  .  The second op
f1b0: 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 74 68  tion opens.** th
f1c0: 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72  e database for r
f1d0: 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
f1e0: 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
f1f0: 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
f200: 69 66 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 6c  if.** if the fil
f210: 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
f220: 63 74 65 64 2e 20 20 49 6e 20 65 69 74 68 65 72  cted.  In either
f230: 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
f240: 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 0a  se must already.
f250: 2a 2a 20 65 78 69 73 74 20 6f 72 20 61 6e 20 65  ** exist or an e
f260: 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
f270: 2e 20 20 54 68 65 20 74 68 69 72 64 20 6f 70 74  .  The third opt
f280: 69 6f 6e 20 6f 70 65 6e 73 20 74 68 65 20 64 61  ion opens the da
f290: 74 61 62 61 73 65 0a 2a 2a 20 66 6f 72 20 72 65  tabase.** for re
f2a0: 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
f2b0: 67 20 61 6e 64 20 63 72 65 61 74 65 73 20 69 74  g and creates it
f2c0: 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
f2d0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 0a 2a  already exist..*
f2e0: 2a 20 54 68 65 20 74 68 69 72 64 20 6f 70 74 69  * The third opti
f2f0: 6f 6e 73 20 69 73 20 62 65 68 61 76 69 6f 72 20  ons is behavior 
f300: 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
f310: 73 65 64 20 66 6f 72 20 5b 73 71 6c 69 74 65 33  sed for [sqlite3
f320: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
f330: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
f340: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
f350: 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
f360: 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
f370: 20 70 72 69 76 61 74 65 0a 2a 2a 20 69 6e 2d 6d   private.** in-m
f380: 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
f390: 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
f3a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
f3b0: 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  his in-memory.**
f3c0: 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
f3d0: 61 6e 69 73 68 20 77 68 65 6e 20 74 68 65 20 64  anish when the d
f3e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f3f0: 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
f400: 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
f410: 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
f420: 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
f430: 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
f440: 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 74 68 61  filenames.** tha
f450: 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
f460: 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 20   ":" character. 
f470: 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
f480: 65 64 20 74 68 61 74 20 0a 2a 2a 20 77 68 65 6e  ed that .** when
f490: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
f4a0: 6e 61 6d 65 20 72 65 61 6c 6c 79 20 64 6f 65 73  name really does
f4b0: 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 22   begin with.** "
f4c0: 3a 22 20 74 68 61 74 20 79 6f 75 20 70 72 65 66  :" that you pref
f4d0: 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
f4e0: 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
f4f0: 6c 69 6b 65 20 22 2e 2f 22 20 74 6f 0a 2a 2a 20  like "./" to.** 
f500: 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
f510: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
f520: 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
f530: 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
f540: 61 20 70 72 69 76 61 74 65 20 74 65 6d 70 6f 72  a private tempor
f550: 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
f560: 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
f570: 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
f580: 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
f590: 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
f5a0: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
f5b0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
f5c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f5d0: 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
f5e0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
f5f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
f600: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
f610: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
f620: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
f630: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
f640: 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
f650: 74 69 6e 67 20 73 79 73 74 65 6d 20 0a 2a 2a 20  ting system .** 
f660: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
f670: 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
f680: 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
f690: 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 0a 2a  d use.  If the.*
f6a0: 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
f6b0: 65 72 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  er is a NULL poi
f6c0: 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
f6d0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
f6e0: 66 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 69 73  fs].** object is
f6f0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
f700: 4e 6f 74 65 20 74 6f 20 77 69 6e 64 6f 77 73 20  Note to windows 
f710: 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
f720: 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
f730: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
f740: 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 5b 73  rgument.** of [s
f750: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
f760: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
f770: 5f 76 32 28 29 5d 20 6d 75 73 74 20 62 65 20 55  _v2()] must be U
f780: 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
f790: 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
f7a0: 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
f7b0: 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
f7c0: 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
f7d0: 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
f7e0: 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
f7f0: 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
f800: 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
f810: 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
f820: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f830: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
f840: 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
f850: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
f860: 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
f870: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
f880: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
f890: 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
f8a0: 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
f8b0: 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
f8c0: 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
f8d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
f8e0: 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
f8f0: 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
f900: 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
f910: 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
f920: 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
f930: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
f940: 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
f950: 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
f960: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
f970: 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
f980: 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
f990: 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
f9a0: 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
f9b0: 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
f9c0: 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
f9d0: 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
f9e0: 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
f9f0: 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
fa00: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
fa10: 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
fa20: 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
fa30: 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
fa40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fa50: 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
fa60: 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
fa70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
fa80: 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
fa90: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
faa0: 65 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eric.** [SQLITE_
fab0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
fac0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
fad0: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
fae0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 0a  ed result code].
faf0: 2a 2a 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  ** for the most 
fb00: 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
fb10: 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
fb20: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
fb30: 69 74 68 20 5b 73 71 6c 69 74 65 33 5d 20 68 61  ith [sqlite3] ha
fb40: 6e 64 6c 65 20 27 64 62 27 2e 20 20 49 66 20 61  ndle 'db'.  If a
fb50: 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
fb60: 66 61 69 6c 65 64 20 62 75 74 20 74 68 65 0a 2a  failed but the.*
fb70: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  * most recent AP
fb80: 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
fb90: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
fba0: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
fbb0: 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 73 20  errcode().** is 
fbc0: 75 6e 64 65 66 69 6e 65 64 2e 20 0a 2a 2a 0a 2a  undefined. .**.*
fbd0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
fbe0: 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
fbf0: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
fc00: 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
fc10: 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
fc20: 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
fc30: 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
fc40: 72 20 55 54 46 38 20 6f 72 20 55 54 46 31 36 20  r UTF8 or UTF16 
fc50: 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
fc60: 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
fc70: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
fc80: 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
fc90: 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 20  ged internally. 
fca0: 20 54 68 65 20 0a 2a 2a 20 73 74 72 69 6e 67 20   The .** string 
fcb0: 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69 74 74  may be overwritt
fcc0: 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
fcd0: 64 20 62 79 20 73 75 62 73 65 71 75 65 6e 74 20  d by subsequent 
fce0: 63 61 6c 6c 73 20 74 6f 20 53 51 4c 69 74 65 0a  calls to SQLite.
fcf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  ** interface fun
fd00: 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 61  ctions..**.** Ca
fd10: 6c 6c 73 20 74 6f 20 6d 61 6e 79 20 73 71 6c 69  lls to many sqli
fd20: 74 65 33 5f 2a 20 66 75 6e 63 74 69 6f 6e 73 20  te3_* functions 
fd30: 73 65 74 20 74 68 65 20 65 72 72 6f 72 20 63 6f  set the error co
fd40: 64 65 20 61 6e 64 20 73 74 72 69 6e 67 20 72 65  de and string re
fd50: 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
fd60: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
fd70: 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
fd80: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
fd90: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
fda0: 2a 20 28 6f 76 65 72 77 72 69 74 69 6e 67 20 74  * (overwriting t
fdb0: 68 65 20 70 72 65 76 69 6f 75 73 20 76 61 6c 75  he previous valu
fdc0: 65 73 29 2e 20 4e 6f 74 65 20 74 68 61 74 20 63  es). Note that c
fdd0: 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
fde0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
fdf0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
fe00: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
fe10: 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 74 68 65  _errmsg16()] the
fe20: 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
fe30: 66 66 65 63 74 20 74 68 65 0a 2a 2a 20 72 65 73  ffect the.** res
fe40: 75 6c 74 73 20 6f 66 20 66 75 74 75 72 65 20 69  ults of future i
fe50: 6e 76 6f 63 61 74 69 6f 6e 73 2e 20 20 43 61 6c  nvocations.  Cal
fe60: 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
fe70: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
fe80: 65 74 75 72 6e 0a 2a 2a 20 61 6e 20 65 72 72 6f  eturn.** an erro
fe90: 72 20 63 6f 64 65 20 28 65 78 61 6d 70 6c 65 3a  r code (example:
fea0: 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
feb0: 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
fec0: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 65 72  ** change the er
fed0: 72 6f 72 20 63 6f 64 65 20 72 65 74 75 72 6e 65  ror code returne
fee0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
fef0: 65 2e 20 20 49 6e 74 65 72 66 61 63 65 73 20 74  e.  Interfaces t
ff00: 68 61 74 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 61  hat are.** not a
ff10: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
ff20: 20 73 70 65 63 69 66 69 63 20 64 61 74 61 62 61   specific databa
ff30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 28 65  se connection (e
ff40: 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 5b 73 71 6c  xamples:.** [sql
ff50: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20  ite3_mprintf()] 
ff60: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  or [sqlite3_enab
ff70: 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
ff80: 29 5d 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65  )] do not change
ff90: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 63  .** the return c
ffa0: 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 41 73 73  ode.  .**.** Ass
ffb0: 75 6d 69 6e 67 20 6e 6f 20 6f 74 68 65 72 20 69  uming no other i
ffc0: 6e 74 65 72 76 65 6e 69 6e 67 20 73 71 6c 69 74  ntervening sqlit
ffd0: 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 73 20 61  e3_* API calls a
ffe0: 72 65 20 6d 61 64 65 2c 20 74 68 65 20 65 72 72  re made, the err
fff0: 6f 72 0a 2a 2a 20 63 6f 64 65 20 72 65 74 75 72  or.** code retur
10000 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
10010 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74  tion is associat
10020 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
10030 20 65 72 72 6f 72 20 61 73 0a 2a 2a 20 74 68 65   error as.** the
10040 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
10050 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
10060 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
10070 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
10080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10090 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
100a0 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
100b0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
100c0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
100d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
100e0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
100f0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10100 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
10110 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
10120 20 49 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   Instance of thi
10130 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
10140 6e 74 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74  nt single SQL st
10150 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 0a  atements.  This.
10160 2a 2a 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ** is variously 
10170 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
10180 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
10190 6f 72 20 61 20 0a 2a 2a 20 22 63 6f 6d 70 69 6c  or a .** "compil
101a0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
101b0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
101c0 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
101d0 20 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66   .** The life of
101e0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
101f0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
10200 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
10210 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
10220 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
10230 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
10240 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
10250 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
10260 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
10270 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
10280 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
10290 65 74 65 72 73 20 75 73 69 6e 67 0a 2a 2a 20 20  eters using.**  
102a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
102b0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
102c0 5f 62 69 6e 64 5f 2a 20 69 6e 74 65 72 66 61 63  _bind_* interfac
102d0 65 73 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  es]..** <li> Run
102e0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
102f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
10300 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
10310 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
10320 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
10330 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
10340 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
10350 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
10360 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
10370 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
10380 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
10390 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
103a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
103b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
103c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
103d0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
103e0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
103f0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
10400 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
10410 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
10420 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10430 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
10440 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
10450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10460 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
10470 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
10480 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
10490 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
104a0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
104b0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
104c0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
104d0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
104e0 65 20 72 6f 75 74 69 6e 65 73 2e 20 0a 2a 2a 0a  e routines. .**.
104f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10500 75 6d 65 6e 74 20 22 64 62 22 20 69 73 20 61 6e  ument "db" is an
10510 20 5b 73 71 6c 69 74 65 33 20 7c 20 53 51 4c 69   [sqlite3 | SQLi
10520 74 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  te database hand
10530 6c 65 5d 20 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  le] .** obtained
10540 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 20 63 61   from a prior ca
10550 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
10560 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
10570 5f 6f 70 65 6e 5f 76 32 28 29 5d 0a 2a 2a 20 6f  _open_v2()].** o
10580 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
10590 36 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 65 63  6()]..** The sec
105a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 22 7a 53  ond argument "zS
105b0 71 6c 22 20 69 73 20 74 68 65 20 73 74 61 74 65  ql" is the state
105c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
105d0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
105e0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
105f0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
10600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
10610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
10620 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
10630 74 65 72 66 61 63 65 73 20 75 73 65 73 20 55 54  terfaces uses UT
10640 46 2d 38 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  F-8 and sqlite3_
10650 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
10660 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
10670 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
10680 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  F-16..**.** If t
10690 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
106a0 74 20 69 73 20 6c 65 73 73 0a 2a 2a 20 74 68 61  t is less.** tha
106b0 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
106c0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
106d0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
106e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 49 66 0a 2a  erminator.  If.*
106f0 2a 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  * nByte is non-n
10700 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
10710 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
10720 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 62 79  number of .** by
10730 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
10740 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
10750 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
10760 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
10770 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
10780 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
10790 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
107a0 20 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 6e   .** until the n
107b0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
107c0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
107d0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  rst..**.** *pzTa
107e0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
107f0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
10800 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
10810 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 0a  nd of the first.
10820 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
10830 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 69 73 20   in zSql.  This 
10840 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6d  routine only com
10850 70 69 6c 65 73 20 74 68 65 20 66 69 72 73 74 20  piles the first 
10860 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e 20  statement.** in 
10870 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
10880 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
10890 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e  g to what remain
108a0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
108b0 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
108c0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
108d0 61 20 63 6f 6d 70 69 6c 65 64 20 0a 2a 2a 20 5b  a compiled .** [
108e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 53  sqlite3_stmt | S
108f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72  QL statement str
10900 75 63 74 75 72 65 5d 20 74 68 61 74 20 63 61 6e  ucture] that can
10910 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
10920 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
10930 74 65 70 28 29 5d 2e 20 20 4f 72 20 69 66 20 74  tep()].  Or if t
10940 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
10950 2c 20 2a 70 70 53 74 6d 74 20 6d 61 79 20 62 65  , *ppStmt may be
10960 0a 2a 2a 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e  .** set to NULL.
10970 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74    If the input t
10980 65 78 74 20 63 6f 6e 74 61 69 6e 65 64 20 6e 6f  ext contained no
10990 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
109a0 75 74 20 69 73 20 61 6e 64 0a 2a 2a 20 65 6d 70  ut is and.** emp
109b0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ty string or a c
109c0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
109d0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
109e0 55 4c 4c 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e  ULL.  The callin
109f0 67 0a 2a 2a 20 70 72 6f 63 65 64 75 72 65 20 69  g.** procedure i
10a00 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
10a10 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
10a20 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
10a30 65 6d 65 6e 74 0a 2a 2a 20 75 73 69 6e 67 20 5b  ement.** using [
10a40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
10a50 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
10a60 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
10a70 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
10a80 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
10a90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
10aa0 74 68 65 72 77 69 73 65 20 61 6e 20 0a 2a 2a 20  therwise an .** 
10ab0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20  [SQLITE_ERROR | 
10ac0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
10ad0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
10ae0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
10af0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
10b00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
10b10 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
10b20 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
10b30 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
10b40 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
10b50 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
10b60 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
10b70 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
10b80 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
10b90 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
10ba0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e  scouraged..** In
10bb0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
10bc0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
10bd0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
10be0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
10bf0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
10c00 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
10c10 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
10c20 74 68 65 20 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c  the .** original
10c30 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
10c40 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
10c50 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
10c60 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
10c70 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
10c80 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
10c90 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
10ca0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
10cb0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
10cc0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
10cd0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
10ce0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
10cf0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
10d00 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
10d10 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
10d20 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
10d30 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
10d40 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
10d50 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
10d60 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
10d70 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 20 61  has changed in a
10d80 20 77 61 79 0a 2a 2a 20 74 68 61 74 20 6d 61 6b   way.** that mak
10d90 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
10da0 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
10db0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
10dc0 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
10dd0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10de0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
10df0 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
10e00 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
10e10 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
10e20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
10e30 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
10e40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
10e50 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
10e60 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
10e70 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
10e80 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
10e90 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
10ea0 6e 64 20 74 68 65 20 74 65 78 74 20 6f 66 20 74  nd the text of t
10eb0 68 65 20 70 61 72 73 69 6e 67 0a 2a 2a 20 65 72  he parsing.** er
10ec0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
10ed0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
10ee0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
10ef0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
10f00 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
10f10 72 6f 72 20 6f 63 63 75 72 73 2c 20 0a 2a 2a 20  ror occurs, .** 
10f20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
10f30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
10f40 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
10f50 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
10f60 4f 52 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OR | result code
10f70 73 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  s] or.** [SQLITE
10f80 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
10f90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
10fa0 64 65 73 5d 20 73 75 63 68 20 61 73 20 64 69 72  des] such as dir
10fb0 65 63 74 6c 79 2e 0a 2a 2a 20 54 68 65 20 6c 65  ectly..** The le
10fc0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
10fd0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
10fe0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
10ff0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
11000 72 69 63 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  ric.** [SQLITE_E
11010 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
11020 65 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  e and you would 
11030 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
11040 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 0a 2a 2a  econd call to.**
11050 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
11060 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
11070 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
11080 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
11090 70 72 6f 62 6c 65 6d 2e 0a 2a 2a 20 57 69 74 68  problem..** With
110a0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
110b0 65 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  e interfaces, th
110c0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
110d0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
110e0 72 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65 64  r is.** returned
110f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
11100 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
11110 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
11120 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
11130 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
11140 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
11150 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
11160 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
11170 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
11180 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
11190 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
111a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
111b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
111c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
111d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
111e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
111f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
11200 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
11210 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
11220 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
11230 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
11240 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
11250 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
11260 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
11270 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
11280 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
11290 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
112a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
112b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
112c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
112d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
112e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
112f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
11300 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
11310 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
11320 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
11330 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
11340 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
11350 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
11360 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
11370 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
11380 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
11390 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
113a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
113b0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
113c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
113d0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
113e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
113f0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
11400 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
11410 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
11420 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
11430 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
11440 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
11450 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
11460 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
11470 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
11480 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
11490 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
114a0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
114b0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
114c0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
114d0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
114e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
114f0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
11500 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
11510 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
11520 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
11530 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
11540 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
11550 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
11560 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
11570 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
11580 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
11590 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
115a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
115b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
115c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
115d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
115e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
115f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
11600 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
11610 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
11620 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
11630 2a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6f  * Retrieve the o
11640 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74  riginal SQL stat
11650 65 6d 65 6e 74 20 61 73 73 6f 63 69 61 74 65 64  ement associated
11660 20 77 69 74 68 20 61 20 63 6f 6d 70 69 6c 65 64   with a compiled
11670 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 69 6e   statement.** in
11680 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2e   UTF-8 encoding.
11690 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 63 6f  .**.** If the co
116a0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
116b0 6d 65 6e 74 20 70 61 73 73 65 64 20 61 73 20 61  ment passed as a
116c0 6e 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 63  n argument was c
116d0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 0a 2a 2a  ompiled using.**
116e0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
116f0 70 72 65 70 61 72 65 5f 76 32 20 6f 72 20 73 71  prepare_v2 or sq
11700 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
11710 76 32 2c 20 74 68 65 6e 20 74 68 69 73 20 66 75  v2, then this fu
11720 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e  nction.** return
11730 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
11740 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 20   nul-terminated 
11750 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
11760 67 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  g a copy of.** t
11770 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  he original SQL 
11780 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 70  statement. The p
11790 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
117a0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
117b0 65 6e 74 0a 2a 2a 20 69 73 20 64 65 6c 65 74 65  ent.** is delete
117c0 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
117d0 66 69 6e 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a  finalize()..**.*
117e0 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  * If the stateme
117f0 6e 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  nt was compiled 
11800 75 73 69 6e 67 20 65 69 74 68 65 72 20 6f 66 20  using either of 
11810 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
11820 66 61 63 65 73 20 0a 2a 2a 20 73 71 6c 69 74 65  faces .** sqlite
11830 33 5f 70 72 65 70 61 72 65 28 29 20 6f 72 20 73  3_prepare() or s
11840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
11850 28 29 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  (), this functio
11860 6e 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  n returns NULL..
11870 2a 2a 20 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52  ** .****** EXPER
11880 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63  IMENTAL - subjec
11890 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
118a0 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a  out notice *****
118b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 63 6f 6e  *********.*/.con
118c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
118d0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
118e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
118f0 2a 20 43 41 50 49 33 52 45 46 3a 20 20 44 79 6e  * CAPI3REF:  Dyn
11900 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
11910 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  alue Object.**.*
11920 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
11930 6e 61 6d 69 63 20 74 79 70 69 6e 67 20 66 6f 72  namic typing for
11940 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
11950 74 6f 72 65 73 2e 20 20 56 61 6c 75 65 73 20 63  tores.  Values c
11960 61 6e 20 0a 2a 2a 20 62 65 20 69 6e 74 65 67 65  an .** be intege
11970 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
11980 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
11990 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
119a0 4c 4c 2e 20 20 57 68 65 6e 0a 2a 2a 20 70 61 73  LL.  When.** pas
119b0 73 69 6e 67 20 61 72 6f 75 6e 64 20 76 61 6c 75  sing around valu
119c0 65 73 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 65  es internally, e
119d0 61 63 68 20 76 61 6c 75 65 20 69 73 20 72 65 70  ach value is rep
119e0 72 65 73 65 6e 74 65 64 20 61 73 0a 2a 2a 20 61  resented as.** a
119f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
11a00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
11a10 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64  object..*/.typed
11a20 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
11a30 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
11a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53  .** CAPI3REF:  S
11a50 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
11a60 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
11a70 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
11a80 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
11a90 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
11aa0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
11ab0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
11ac0 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
11ad0 6e 74 65 72 20 74 6f 20 73 75 63 68 20 61 6e 20  nter to such an 
11ae0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 0a 2a 2a  object is the.**
11af0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11b00 20 74 6f 20 75 73 65 72 2d 64 65 66 69 6e 65 64   to user-defined
11b10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 0a   SQL functions..
11b20 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11b30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
11b40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
11b50 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
11b60 45 46 3a 20 20 42 69 6e 64 69 6e 67 20 56 61 6c  EF:  Binding Val
11b70 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
11b80 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 0a 2a 2a  Statements.**.**
11b90 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
11ba0 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
11bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
11bc0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
11bd0 61 6e 74 73 2c 0a 2a 2a 20 6f 6e 65 20 6f 72 20  ants,.** one or 
11be0 6d 6f 72 65 20 6c 69 74 65 72 61 6c 73 20 63 61  more literals ca
11bf0 6e 20 62 65 20 72 65 70 6c 61 63 65 20 62 79 20  n be replace by 
11c00 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
11c10 6e 65 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 66  ne of these.** f
11c20 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
11c30 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
11c40 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
11c50 3e 20 20 3a 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20  >  :AAA.** <li> 
11c60 20 40 41 41 41 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @AAA.** <li>  $
11c70 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
11c80 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
11c90 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
11ca0 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
11cb0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
11cc0 0a 2a 2a 20 41 41 41 20 69 73 20 61 6e 20 61 6c  .** AAA is an al
11cd0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
11ce0 69 66 69 65 72 20 61 6e 64 20 56 56 56 20 69 73  ifier and VVV is
11cf0 20 61 20 76 61 72 69 61 62 6c 65 20 6e 61 6d 65   a variable name
11d00 20 61 63 63 6f 72 64 69 6e 67 0a 2a 2a 20 74 6f   according.** to
11d10 20 74 68 65 20 73 79 6e 74 61 78 20 72 75 6c 65   the syntax rule
11d20 73 20 6f 66 20 74 68 65 20 54 43 4c 20 70 72 6f  s of the TCL pro
11d30 67 72 61 6d 6d 69 6e 67 20 6c 61 6e 67 75 61 67  gramming languag
11d40 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73  e..** The values
11d50 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
11d60 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
11d70 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
11d80 72 20 6e 61 6d 65 73 22 29 0a 2a 2a 20 63 61 6e  r names").** can
11d90 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
11da0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
11db0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
11dc0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
11dd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
11de0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
11df0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
11e00 6e 65 73 20 61 6c 77 61 79 73 20 69 73 20 61 20  nes always is a 
11e10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
11e20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
11e30 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
11e40 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
11e50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
11e60 2a 2a 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  ** its variants.
11e70 20 20 54 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20    The second.** 
11e80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
11e90 69 6e 64 65 78 20 6f 66 20 74 68 65 20 70 61 72  index of the par
11ea0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
11eb0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
11ec0 61 6d 65 74 65 72 20 68 61 73 0a 2a 2a 20 61 6e  ameter has.** an
11ed0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 57 68 65   index of 1. Whe
11ee0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
11ef0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
11f00 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
11f10 65 2c 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 6e 64  e, second.** and
11f20 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
11f30 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
11f40 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
11f50 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
11f60 72 72 65 6e 63 65 2e 20 20 54 68 65 20 69 6e 64  rrence.  The ind
11f70 65 78 20 66 6f 72 0a 2a 2a 20 6e 61 6d 65 64 20  ex for.** named 
11f80 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
11f90 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
11fa0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
11fb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
11fc0 5f 6e 61 6d 65 28 29 5d 20 41 50 49 20 69 66 20  _name()] API if 
11fd0 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
11fe0 64 65 78 20 66 6f 72 20 22 3f 4e 4e 4e 22 0a 2a  dex for "?NNN".*
11ff0 2a 20 70 61 72 61 6d 65 74 65 73 20 69 73 20 74  * parametes is t
12000 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
12010 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
12020 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
12030 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f 6d 70  n 1 and the comp
12040 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61 72 61  ile-time.** para
12050 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d 41 58  meter SQLITE_MAX
12060 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
12070 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
12080 20 39 39 39 29 2e 0a 2a 2a 20 53 65 65 20 3c 61   999)..** See <a
12090 20 68 72 65 66 3d 22 6c 69 6d 69 74 73 2e 68 74   href="limits.ht
120a0 6d 6c 22 3e 6c 69 6d 69 74 73 2e 68 74 6d 6c 3c  ml">limits.html<
120b0 2f 61 3e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  /a> for addition
120c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
120d0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
120e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
120f0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
12100 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
12110 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 0a 2a  **.** In those.*
12120 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
12130 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
12140 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
12150 65 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  e is the number 
12160 6f 66 20 62 79 74 65 73 0a 2a 2a 20 69 6e 20 74  of bytes.** in t
12170 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
12180 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
12190 76 61 6c 75 65 20 69 73 20 74 68 65 20 6e 75 6d  value is the num
121a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
121b0 74 68 65 0a 2a 2a 20 73 74 72 69 6e 67 2c 20 6e  the.** string, n
121c0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
121d0 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 54 68   characters.  Th
121e0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
121f0 79 74 65 73 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ytes does not in
12200 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 2d 74  clude the zero-t
12210 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
12220 20 65 6e 64 20 6f 66 20 73 74 72 69 6e 67 73 2e   end of strings.
12230 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
12240 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
12250 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
12260 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
12270 67 20 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  g is.** number o
12280 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
12290 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
122a0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
122b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
122c0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
122d0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
122e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
122f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
12300 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
12310 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
12320 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
12330 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 74 65  he BLOB or.** te
12340 78 74 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  xt after SQLite 
12350 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
12360 68 20 69 74 2e 20 20 49 66 20 74 68 65 20 66 69  h it.  If the fi
12370 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 20  fth argument is 
12380 74 68 65 0a 2a 2a 20 73 70 65 63 69 61 6c 20 76  the.** special v
12390 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
123a0 54 49 43 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c  TIC], then the l
123b0 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20 74  ibrary assumes t
123c0 68 61 74 20 74 68 65 20 69 6e 66 6f 72 6d 61 74  hat the informat
123d0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 20 73 74 61  ion.** is in sta
123e0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
123f0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
12400 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
12410 65 64 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 66  ed.  If the.** f
12420 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
12430 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
12440 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
12450 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
12460 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 70 72 69  s its.** own pri
12470 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
12480 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
12490 79 2c 20 62 65 66 6f 72 65 20 74 68 65 20 73 71  y, before the sq
124a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
124b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
124c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
124d0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
124e0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
124f0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
12500 67 74 68 20 6e 20 74 68 61 74 0a 2a 2a 20 69 73  gth n that.** is
12510 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
12520 6f 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  os.  A zeroblob 
12530 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
12540 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
12550 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
12560 72 20 74 6f 20 68 6f 6c 64 20 69 74 20 73 69 7a  r to hold it siz
12570 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
12580 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
12590 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
125a0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
125b0 76 65 20 61 73 20 70 6c 61 63 65 2d 68 6f 6c 64  ve as place-hold
125c0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
125d0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
125e0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
125f0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
12600 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
12610 6e 63 72 65 6d 65 6e 74 20 42 4c 4f 42 20 49 2f  ncrement BLOB I/
12620 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 20  O] routines.  A 
12630 6e 65 67 61 74 69 76 65 0a 2a 2a 20 76 61 6c 75  negative.** valu
12640 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
12650 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
12660 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
12670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12680 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
12690 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
126a0 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
126b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
126c0 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
126d0 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
126e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
126f0 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
12700 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
12710 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
12720 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
12730 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
12740 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
12750 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
12760 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
12770 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
12780 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
12790 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
127a0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
127b0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
127c0 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
127d0 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
127e0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
127f0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
12800 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
12810 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
12820 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
12830 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
12840 61 6c 6c 6f 63 20 66 61 69 6c 73 2e 0a 2a 2a 20  alloc fails..** 
12850 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
12860 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
12870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
12880 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 76 69  e called on a vi
12890 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
128a0 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
128b0 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
128c0 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
128d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2f  en finalized..*/
128e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
128f0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
12900 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
12910 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
12920 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
12930 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
12940 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
12950 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
12960 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
12970 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
12980 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
12990 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
129a0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
129b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
129c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
129d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
129e0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
129f0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
12a00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
12a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
12a20 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
12a30 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
12a40 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
12a50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
12a60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
12a70 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
12a80 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
12a90 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
12aa0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
12ab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
12ac0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
12ad0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
12ae0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
12af0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
12b00 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
12b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12b20 20 4e 75 6d 62 65 72 20 4f 66 20 48 6f 73 74 20   Number Of Host 
12b30 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
12b40 20 52 65 74 75 72 6e 20 74 68 65 20 6c 61 72 67   Return the larg
12b50 65 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  est host paramet
12b60 65 72 20 69 6e 64 65 78 20 69 6e 20 74 68 65 20  er index in the 
12b70 70 72 65 63 6f 6d 70 69 6c 65 64 20 73 74 61 74  precompiled stat
12b80 65 6d 65 6e 74 20 67 69 76 65 6e 0a 2a 2a 20 61  ement given.** a
12b90 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 2e 20  s the argument. 
12ba0 20 57 68 65 6e 20 74 68 65 20 68 6f 73 74 20 70   When the host p
12bb0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 6f 66  arameters are of
12bc0 20 74 68 65 20 66 6f 72 6d 73 20 6c 69 6b 65 20   the forms like 
12bd0 22 3a 41 41 41 22 0a 2a 2a 20 6f 72 20 22 3f 22  ":AAA".** or "?"
12be0 2c 20 74 68 65 6e 20 74 68 65 79 20 61 72 65 20  , then they are 
12bf0 61 73 73 69 67 6e 65 64 20 73 65 71 75 65 6e 74  assigned sequent
12c00 69 61 6c 20 69 6e 63 72 65 61 73 69 6e 67 20 6e  ial increasing n
12c10 75 6d 62 65 72 73 20 62 65 67 69 6e 6e 69 6e 67  umbers beginning
12c20 0a 2a 2a 20 77 69 74 68 20 6f 6e 65 2c 20 73 6f  .** with one, so
12c30 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
12c40 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
12c50 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 2e  r of parameters.
12c60 20 20 48 6f 77 65 76 65 72 0a 2a 2a 20 69 66 20    However.** if 
12c70 74 68 65 20 73 61 6d 65 20 68 6f 73 74 20 70 61  the same host pa
12c80 72 61 6d 65 74 65 72 20 6e 61 6d 65 20 69 73 20  rameter name is 
12c90 75 73 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  used multiple ti
12ca0 6d 65 73 2c 20 65 61 63 68 20 6f 63 63 75 72 72  mes, each occurr
12cb0 61 6e 63 65 0a 2a 2a 20 69 73 20 67 69 76 65 6e  ance.** is given
12cc0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
12cd0 2c 20 73 6f 20 74 68 65 20 76 61 6c 75 65 20 72  , so the value r
12ce0 65 74 75 72 6e 65 64 20 69 6e 20 74 68 61 74 20  eturned in that 
12cf0 63 61 73 65 20 69 73 20 74 68 65 20 6e 75 6d 62  case is the numb
12d00 65 72 0a 2a 2a 20 6f 66 20 75 6e 69 71 75 65 20  er.** of unique 
12d10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
12d20 61 6d 65 73 2e 20 20 49 66 20 68 6f 73 74 20 70  ames.  If host p
12d30 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
12d40 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 0a 2a 2a 20   form "?NNN".** 
12d50 61 72 65 20 75 73 65 64 20 28 77 68 65 72 65 20  are used (where 
12d60 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
12d70 72 29 20 74 68 65 6e 20 74 68 65 72 65 20 6d 69  r) then there mi
12d80 67 68 74 20 62 65 20 67 61 70 73 20 69 6e 20 74  ght be gaps in t
12d90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 69 6e 67 20  he.** numbering 
12da0 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20 72 65  and the value re
12db0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 69  turned by this i
12dc0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
12dd0 69 6e 64 65 78 20 6f 66 20 74 68 65 0a 2a 2a 20  index of the.** 
12de0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 77  host parameter w
12df0 69 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20  ith the largest 
12e00 69 6e 64 65 78 20 76 61 6c 75 65 2e 0a 2a 2a 0a  index value..**.
12e10 2a 2a 20 54 68 65 20 70 72 65 70 61 72 65 64 20  ** The prepared 
12e20 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20 6e  statement must n
12e30 6f 74 20 62 65 20 5b 73 71 6c 69 74 65 33 5f 66  ot be [sqlite3_f
12e40 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
12e50 7a 65 64 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  zed].** prior to
12e60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
12e70 74 75 72 6e 6e 69 6e 67 2e 20 20 4f 74 68 65 72  turnning.  Other
12e80 77 69 73 65 20 74 68 65 20 72 65 73 75 6c 74 73  wise the results
12e90 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a   are undefined.*
12ea0 2a 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  * and probably u
12eb0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 69  ndesirable..*/.i
12ec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
12ed0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
12ee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
12ef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12f00 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
12f10 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
12f20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
12f30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
12f40 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  o the name of th
12f50 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
12f60 20 69 6e 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74   in a .** [sqlit
12f70 65 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72  e3_stmt | prepar
12f80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
12f90 2a 20 48 6f 73 74 20 70 61 72 61 6d 65 74 65 72  * Host parameter
12fa0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3a  s of the form ":
12fb0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
12fc0 72 20 22 24 56 56 56 22 20 68 61 76 65 20 61 20  r "$VVV" have a 
12fd0 6e 61 6d 65 0a 2a 2a 20 77 68 69 63 68 20 69 73  name.** which is
12fe0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3a 41 41   the string ":AA
12ff0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
13000 22 24 56 56 56 22 2e 20 20 0a 2a 2a 20 49 6e 20  "$VVV".  .** In 
13010 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
13020 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
13030 22 24 22 20 6f 72 20 22 40 22 0a 2a 2a 20 69 73  "$" or "@".** is
13040 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
13050 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  t of the name..*
13060 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20  * Parameters of 
13070 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 6f 72 20  the form "?" or 
13080 22 3f 4e 4e 4e 22 20 68 61 76 65 20 6e 6f 20 6e  "?NNN" have no n
13090 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ame..**.** The f
130a0 69 72 73 74 20 62 6f 75 6e 64 20 70 61 72 61 6d  irst bound param
130b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
130c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
130d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
130e0 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
130f0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
13100 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
13110 6e 61 6d 65 6c 65 73 73 2c 0a 2a 2a 20 74 68 65  nameless,.** the
13120 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
13130 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
13140 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
13150 79 73 20 69 6e 20 74 68 65 0a 2a 2a 20 55 54 46  ys in the.** UTF
13160 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
13170 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
13180 72 61 6d 65 74 65 72 20 77 61 73 20 6f 72 69 67  rameter was orig
13190 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
131a0 0a 2a 2a 20 61 73 20 55 54 46 2d 31 36 20 69 6e  .** as UTF-16 in
131b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
131c0 65 31 36 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  e16()] or [sqlit
131d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
131e0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
131f0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
13200 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
13210 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
13220 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
13230 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
13240 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
13250 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
13260 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
13270 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
13280 20 6f 66 20 61 20 68 6f 73 74 20 70 61 72 61 6d   of a host param
13290 65 74 65 72 20 77 69 74 68 20 74 68 65 20 67 69  eter with the gi
132a0 76 65 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  ven name..** The
132b0 20 6e 61 6d 65 20 6d 75 73 74 20 6d 61 74 63 68   name must match
132c0 20 65 78 61 63 74 6c 79 2e 20 20 49 66 20 6e 6f   exactly.  If no
132d0 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
132e0 74 68 65 20 67 69 76 65 6e 20 6e 61 6d 65 20 69  the given name i
132f0 73 20 0a 2a 2a 20 66 6f 75 6e 64 2c 20 72 65 74  s .** found, ret
13300 75 72 6e 20 30 2e 20 20 50 61 72 61 6d 65 74 65  urn 0.  Paramete
13310 72 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  r names must be 
13320 55 54 46 38 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  UTF8..*/.int sql
13330 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
13340 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
13350 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
13360 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
13370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
13380 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
13390 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
133a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 43  tatement.**.** C
133b0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
133c0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
133d0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
133e0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ()] does not.** 
133f0 72 65 73 65 74 20 74 68 65 20 5b 73 71 6c 69 74  reset the [sqlit
13400 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
13410 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 0a 2a  indings] on a .*
13420 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
13430 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
13440 6d 65 6e 74 5d 2e 20 20 55 73 65 20 74 68 69 73  ment].  Use this
13450 20 72 6f 75 74 69 6e 65 20 74 6f 0a 2a 2a 20 72   routine to.** r
13460 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
13470 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
13480 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13490 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
134a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
134b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
134c0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
134d0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
134e0 65 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  et.**.** Return 
134f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
13500 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
13510 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
13520 20 62 79 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   by the .** [sql
13530 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d 70  ite3_stmt | comp
13540 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
13550 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  nt]. This routin
13560 65 20 72 65 74 75 72 6e 73 20 30 0a 2a 2a 20 69  e returns 0.** i
13570 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
13580 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
13590 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
135a0 20 64 61 74 61 20 28 66 6f 72 20 0a 2a 2a 20 65   data (for .** e
135b0 78 61 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45  xample an UPDATE
135c0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
135d0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
135e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
135f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
13600 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
13610 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
13620 65 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  et.**.** These r
13630 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
13640 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
13650 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
13660 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
13670 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
13680 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
13690 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
136a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
136b0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
136c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
136d0 20 61 20 55 54 46 38 20 73 74 72 69 6e 67 20 61   a UTF8 string a
136e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
136f0 6e 5f 6e 61 6d 65 31 36 28 29 0a 2a 2a 20 72 65  n_name16().** re
13700 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
13710 74 6f 20 61 20 55 54 46 31 36 20 73 74 72 69 6e  to a UTF16 strin
13720 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
13730 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
13740 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  * [sqlite3_stmt 
13750 7c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  | prepared state
13760 6d 65 6e 74 5d 20 74 68 61 74 20 69 6d 70 6c 65  ment] that imple
13770 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54  ments the SELECT
13780 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
13790 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
137a0 74 65 72 20 69 73 20 74 68 65 20 63 6f 6c 75 6d  ter is the colum
137b0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
137c0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
137d0 69 73 0a 2a 2a 20 6e 75 6d 62 65 72 20 30 2e 0a  is.** number 0..
137e0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
137f0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
13800 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
13810 20 65 69 74 68 65 72 20 74 68 65 20 0a 2a 2a 20   either the .** 
13820 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13840 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
13850 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
13860 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 6f 72 20 75  alize()].** or u
13870 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
13880 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
13890 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
138a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
138b0 36 28 29 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  6().** on the sa
138c0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
138d0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
138e0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
138f0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
13900 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
13910 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
13920 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
13930 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
13940 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
13950 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
13960 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
13970 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
13980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
13990 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
139a0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
139b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
139c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
139d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
139e0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
139f0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
13a00 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
13a10 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73  esult.**.** Thes
13a20 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
13a30 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
13a40 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
13a50 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
13a60 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
13a70 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
13a80 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  of a SELECT stat
13a90 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d  ement comes from
13aa0 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  ..** The name of
13ab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
13ac0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
13ad0 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
13ae0 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
13af0 55 54 46 38 20 6f 72 20 55 54 46 31 36 20 73 74  UTF8 or UTF16 st
13b00 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
13b10 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
13b20 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
13b30 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
13b40 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
13b50 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
13b60 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
13b70 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
13b80 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
13b90 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
13ba0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
13bb0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
13bc0 6c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  l.** the [sqlite
13bd0 33 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65  3_stmt | prepare
13be0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
13bf0 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
13c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
13c10 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
13c20 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
13c30 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
13c40 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
13c50 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
13c60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ing..**.** The n
13c70 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
13c80 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
13c90 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
13ca0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
13cb0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
13cc0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  olumn..**.** The
13cd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13ce0 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  to the following
13cf0 20 63 61 6c 6c 73 20 69 73 20 61 20 0a 2a 2a 20   calls is a .** 
13d00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20  [sqlite3_stmt | 
13d10 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
13d20 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
13d30 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
13d40 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
13d50 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
13d60 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
13d70 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
13d80 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
13d90 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
13da0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
13db0 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  * If the Nth col
13dc0 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
13dd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
13de0 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a   an expression.*
13df0 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20 61 6e  * or subquery an
13e00 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
13e10 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
13e20 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
13e30 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 4e  ions.** return N
13e40 55 4c 4c 2e 20 4f 74 68 65 72 77 69 73 65 2c 20  ULL. Otherwise, 
13e50 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
13e60 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
13e70 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
13e80 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  e, table and col
13e90 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
13ea0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
13eb0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
13ec0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
13ed0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
13ee0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
13ef0 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
13f00 36 22 20 72 65 74 75 72 6e 20 55 54 46 2d 31 36  6" return UTF-16
13f10 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 73 74 72 69  .** encoded stri
13f20 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
13f30 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
13f40 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  UTF-8..**.** The
13f50 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
13f60 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
13f70 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
13f80 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
13f90 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c  .** SQLITE_ENABL
13fa0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
13fb0 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  A preprocessor s
13fc0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
13fd0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
13fe0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
13ff0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
14000 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
14010 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
14020 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
14030 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
14040 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
14050 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
14060 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
14070 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
14080 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
14090 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
140a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
140b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
140c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
140d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
140e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
140f0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
14100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
14110 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
14120 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
14130 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
14140 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
14150 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
14160 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
14170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
14180 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
14190 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
141a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
141b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
141c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
141d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
141e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
141f0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
14200 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
14210 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Result.**.** The
14220 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14230 20 69 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   is a [sqlite3_s
14240 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64 20 53  tmt | compiled S
14250 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a  QL statement]. .
14260 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
14270 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54  ment is a SELECT
14280 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
14290 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
142a0 20 74 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65   the .** returne
142b0 64 20 72 65 73 75 6c 74 20 73 65 74 20 20 6f 66  d result set  of
142c0 20 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20   that SELECT is 
142d0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
142e0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
142f0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
14300 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
14310 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
14320 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
14330 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
14340 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
14350 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
14360 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
14370 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
14380 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
14390 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
143a0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
143b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
143c0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
143d0 64 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d. For example, 
143e0 69 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  in.** the databa
143f0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
14400 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
14410 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
14420 0a 2a 2a 20 41 6e 64 20 74 68 65 20 66 6f 6c 6c  .** And the foll
14430 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
14440 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
14450 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
14460 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
14470 20 54 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   Then this routi
14480 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
14490 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
144a0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
144b0 6f 6e 64 0a 2a 2a 20 72 65 73 75 6c 74 20 63 6f  ond.** result co
144c0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
144d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
144e0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
144f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 28  sult column.** (
14500 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
14510 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
14520 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
14530 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
14540 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
14550 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
14560 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
14570 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
14580 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
14590 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
145a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
145b0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
145c0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
145d0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
145e0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
145f0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
14600 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
14610 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
14620 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
14630 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
14640 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
14650 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
14660 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
14670 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
14680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
14690 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
146a0 6d 74 20 2a 2c 20 69 6e 74 20 69 29 3b 0a 63 6f  mt *, int i);.co
146b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
146c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
146d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
146e0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a 2a 20  *,int);../* .** 
146f0 43 41 50 49 33 52 45 46 3a 20 20 45 76 61 6c 75  CAPI3REF:  Evalu
14700 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
14710 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
14720 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d   an [sqlite3_stm
14730 74 20 7c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  t | SQL statemen
14740 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
14750 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c 6c  ared with a call
14760 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b 73  .** to either [s
14770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
14780 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
14790 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
147a0 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a 2a   or to one of.**
147b0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
147c0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
147d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
147e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
147f0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  ()],.** then thi
14800 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  s function must 
14810 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
14820 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
14830 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a 20  valuate the .** 
14840 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
14850 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
14860 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
14870 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74 65  this sqlite3_ste
14880 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
14890 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
148a0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
148b0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
148c0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
148d0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
148e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
148f0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
14900 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
14910 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
14920 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
14930 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
14940 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
14950 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
14960 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
14970 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
14980 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
14990 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
149a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
149b0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
149c0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
149d0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
149e0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
149f0 6e 20 74 68 65 20 6c 61 67 61 63 79 20 69 6e 74  n the lagacy int
14a00 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
14a10 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
14a20 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14a30 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c 49  BUSY], .** [SQLI
14a40 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
14a50 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
14a60 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
14a70 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
14a80 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
14a90 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
14aa0 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54 45  he other [SQLITE
14ab0 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
14ac0 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  e].** or [SQLITE
14ad0 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
14ae0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14af0 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  de] might be ret
14b00 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c 6c  urned as.** well
14b10 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
14b20 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
14b30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
14b40 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
14b50 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
14b60 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
14b70 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
14b80 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
14b90 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
14ba0 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
14bb0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
14bc0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
14bd0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
14be0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
14bf0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
14c00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
14c10 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
14c20 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
14c30 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
14c40 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
14c50 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
14c60 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
14c70 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
14c80 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
14c90 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
14ca0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
14cb0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
14cc0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
14cd0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
14ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
14cf0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
14d00 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
14d10 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
14d20 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
14d30 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
14d40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
14d50 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
14d60 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
14d70 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
14d80 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
14d90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14da0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
14db0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
14dc0 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53 51  ta, then .** [SQ
14dd0 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65 74  LITE_ROW] is ret
14de0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
14df0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
14e00 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66 6f  a is ready.** fo
14e10 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
14e20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  the caller. The 
14e30 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
14e40 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  cessed using.** 
14e50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
14e60 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d 6e  umn_int | column
14e70 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
14e80 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
14e90 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
14ea0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
14eb0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
14ec0 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20 5b  f data..** .** [
14ed0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
14ee0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
14ef0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
14f00 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
14f10 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
14f20 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
14f30 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
14f40 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
14f50 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
14f60 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
14f70 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
14f80 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
14f90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
14fa0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
14fb0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
14fc0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
14fd0 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61 6d  error code (exam
14fe0 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple:.** [SQLITE_
14ff0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
15000 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
15010 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
15020 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
15030 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
15040 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
15050 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
15060 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
15070 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64 20  stmt | prepared 
15080 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
15090 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
150a0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
150b0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
150c0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
150d0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
150e0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
150f0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
15100 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
15110 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
15120 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
15130 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
15140 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
15150 65 64 20 6f 6e 20 61 20 5b 73 71 6c 69 74 65 33  ed on a [sqlite3
15160 5f 73 74 6d 74 20 7c 20 70 72 65 70 61 72 65 64  _stmt | prepared
15170 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
15180 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
15190 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
151a0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
151b0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
151c0 61 74 20 68 61 64 20 0a 2a 2a 20 70 72 65 76 69  at had .** previ
151d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
151e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
151f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
15200 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
15210 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
15220 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
15230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
15240 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
15250 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
15260 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
15270 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
15280 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
15290 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
152a0 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74 68 65 20  :</b>.** In the 
152b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
152c0 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  , .** the sqlite
152d0 33 5f 73 74 65 70 28 29 20 41 50 49 20 61 6c 77  3_step() API alw
152e0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
152f0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
15300 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
15310 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
15320 6e 79 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ny error other t
15330 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
15340 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45  ].** and [SQLITE
15350 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
15360 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  ust call [sqlite
15370 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
15380 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
15390 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
153a0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
153b0 65 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 5b 53  e specific.** [S
153c0 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72 65  QLITE_ERROR | re
153d0 73 75 6c 74 20 63 6f 64 65 73 5d 20 74 68 61 74  sult codes] that
153e0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
153f0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
15400 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
15410 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
15420 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
15430 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
15440 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
15450 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
15460 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
15470 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
15480 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
15490 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
154a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
154b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
154c0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
154d0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
154e0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
154f0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
15500 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
15510 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a  )], then the .**
15520 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
15530 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 72  SQLITE_ERROR | r
15540 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65  esult codes] are
15550 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
15560 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
15570 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
15580 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
15590 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
155a0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
155b0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
155c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
155d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 0a 2a 2a 0a  ** CAPI3REF:.**.
155e0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
155f0 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
15600 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
15610 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
15620 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  set..**.** After
15630 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
15640 74 65 33 5f 73 74 65 70 28 29 5d 20 74 68 61 74  te3_step()] that
15650 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
15660 5f 52 4f 57 5d 2c 20 74 68 69 73 20 72 6f 75 74  _ROW], this rout
15670 69 6e 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  ine.** will retu
15680 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
15690 65 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65  e as the [sqlite
156a0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
156b0 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 41  ] function..** A
156c0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
156d0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
156e0 65 64 20 61 6e 20 5b 53 51 4c 49 54 45 5f 44 4f  ed an [SQLITE_DO
156f0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  NE], [SQLITE_BUS
15700 59 5d 2c 20 6f 72 0a 2a 2a 20 61 20 5b 53 51 4c  Y], or.** a [SQL
15710 49 54 45 5f 45 52 52 4f 52 20 7c 20 65 72 72 6f  ITE_ERROR | erro
15720 72 20 63 6f 64 65 5d 2c 20 6f 72 20 62 65 66 6f  r code], or befo
15730 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
15740 28 29 5d 20 68 61 73 20 62 65 65 6e 20 0a 2a 2a  ()] has been .**
15750 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b   called on the [
15760 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70  sqlite3_stmt | p
15770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15780 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  t] for the first
15790 20 74 69 6d 65 2c 0a 2a 2a 20 74 68 69 73 20 72   time,.** this r
157a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
157b0 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ero..*/.int sqli
157c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
157d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
157e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
157f0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
15800 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 0a 2a  l Datatypes.**.*
15810 2a 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  * Every value in
15820 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
15830 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
15840 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
15850 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
15860 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
15870 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
15880 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
15890 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
158a0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
158b0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
158c0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
158d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ul>.**.** These 
158e0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
158f0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
15900 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
15910 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
15920 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
15930 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
15940 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
15950 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
15960 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
15970 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
15980 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
15990 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
159a0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
159b0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
159c0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
159d0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
159e0 54 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  T not.** SQLITE_
159f0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
15a00 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
15a10 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
15a20 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
15a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
15a40 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
15a50 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
15a60 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
15a70 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
15a80 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
15a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
15aa0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
15ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
15ac0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
15ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
15ae0 6c 74 73 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  lts Values From 
15af0 41 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 54 68  A Query.**.** Th
15b00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
15b10 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
15b20 61 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c  about.** a singl
15b30 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
15b40 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72  current result r
15b50 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
15b60 49 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65  In every.** case
15b70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
15b80 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
15b90 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
15ba0 69 74 65 33 5f 73 74 6d 74 20 7c 20 53 51 4c 20  ite3_stmt | SQL 
15bb0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
15bc0 69 73 20 62 65 69 6e 67 0a 2a 2a 20 65 76 61 6c  is being.** eval
15bd0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
15be0 74 65 33 5f 73 74 6d 74 2a 5d 20 74 68 61 74 20  te3_stmt*] that 
15bf0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
15c00 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  m .** [sqlite3_p
15c10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
15c20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
15c30 6e 74 73 29 20 61 6e 64 0a 2a 2a 20 74 68 65 20  nts) and.** the 
15c40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15c50 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
15c60 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
15c70 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
15c80 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72   .** should be r
15c90 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
15ca0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  ft-most column o
15cb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
15cc0 0a 2a 2a 20 68 61 73 20 61 6e 20 69 6e 64 65 78  .** has an index
15cd0 20 6f 66 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20   of 0..**.** If 
15ce0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
15cf0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
15d00 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
15d10 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
15d20 68 65 0a 2a 2a 20 74 68 65 20 63 6f 6c 75 6d 6e  he.** the column
15d30 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
15d40 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
15d50 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
15d60 20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69   .** These routi
15d70 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
15d80 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
15d90 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
15da0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
15db0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
15dc0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
15dd0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
15de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15df0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
15e00 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 73 20  finalize()] has 
15e10 62 65 65 6e 20 63 61 6c 6c 20 73 75 62 73 65 71  been call subseq
15e20 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
15e30 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
15e40 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
15e50 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
15e60 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
15e70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
15e80 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
15e90 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
15ea0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
15eb0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
15ec0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
15ed0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
15ee0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
15ef0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15f00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
15f10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
15f20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
15f30 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
15f40 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
15f50 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
15f60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
15f70 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
15f80 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
15f90 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 20   are undefined. 
15fa0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69   .**.** The sqli
15fb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
15fc0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
15fd0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  s .** [SQLITE_IN
15fe0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
15ff0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
16000 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
16010 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
16020 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
16030 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
16040 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
16050 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
16060 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
16070 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
16080 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
16090 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
160a0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
160b0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
160c0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
160d0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
160e0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
160f0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
16100 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
16110 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
16120 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
16130 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
16140 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
16150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
16160 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
16170 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
16180 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
16190 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
161a0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
161b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
161c0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
161d0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
161e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
161f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
16200 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
16210 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
16220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
16230 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
16240 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16250 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
16260 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
16270 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
16280 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
16290 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
162a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
162b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
162c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
162d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
162e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
162f0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
16300 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
16310 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
16320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
16330 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
16340 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16350 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
16360 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
16370 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
16380 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
16390 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
163a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
163b0 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
163c0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
163d0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
163e0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
163f0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
16400 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
16410 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
16420 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
16430 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
16440 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
16450 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
16460 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
16470 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
16480 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
16490 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
164a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
164b0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
164c0 76 65 6e 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  ven zero-length 
164d0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
164e0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
164f0 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ted.  The return
16500 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
16510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
16520 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
16530 6c 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61  length blob is a
16540 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
16550 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
16560 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
16570 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
16580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
16590 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
165a0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
165b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
165c0 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
165d0 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
165e0 6e 20 55 54 46 2d 31 36 20 69 6e 73 74 65 61 64  n UTF-16 instead
165f0 20 6f 66 20 55 54 46 2d 38 2e 20 20 0a 2a 2a 20   of UTF-8.  .** 
16600 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
16610 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
16620 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
16630 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  t..**.** These r
16640 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
16650 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
16660 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
16670 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
16680 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
16690 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
166a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
166b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
166c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
166d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
166e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
166f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64   internally to d
16700 6f 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  o the conversion
16710 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
16720 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
16730 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
16740 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  the conversions 
16750 74 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c  that.** are appl
16760 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
16770 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
16780 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
16790 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
167a0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
167b0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
167c0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
167d0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
167e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
167f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
16800 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
16810 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
16820 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
16830 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
16840 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
16850 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
16860 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
16870 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
16880 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
16890 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
168a0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
168b0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
168c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
168d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
168e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
168f0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
16900 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
16910 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
16920 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
16930 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
16940 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
16950 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
16960 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
16970 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
16980 73 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54  s for INTEGER->T
16990 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
169a0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
169b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
169c0 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
169d0 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
169e0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
169f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
16a00 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
16a10 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
16a20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
16a30 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
16a40 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
16a50 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
16a60 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
16a70 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
16a80 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
16a90 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
16aa0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
16ab0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
16ac0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
16ad0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
16ae0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
16af0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
16b00 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
16b10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
16b20 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
16b30 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
16b40 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
16b50 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
16b60 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
16b70 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
16b80 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
16b90 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
16ba0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
16bb0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
16bc0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
16bd0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
16be0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
16bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
16c00 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
16c10 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
16c20 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
16c30 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
16c40 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
16c50 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
16c60 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
16c70 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
16c80 73 20 69 74 73 0a 2a 2a 20 6f 6e 20 65 71 75 61  s its.** on equa
16c90 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
16ca0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
16cb0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
16cc0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
16cd0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
16ce0 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
16cf0 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
16d00 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
16d10 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
16d20 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
16d30 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
16d40 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
16d50 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
16d60 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
16d70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
16d80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
16d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16da0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
16db0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
16dc0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
16dd0 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20  nvalidated. .** 
16de0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
16df0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
16e00 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
16e10 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
16e20 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
16e30 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
16e40 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
16e50 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
16e60 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
16e70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
16e80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72   .**          or
16e90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
16ea0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
16eb0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
16ec0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
16ed0 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f           need to
16ee0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
16ef0 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69   string.</p></li
16f00 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
16f10 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
16f20 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
16f30 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
16f40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
16f50 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
16f60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
16f70 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
16f80 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
16f90 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
16fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
16fb0 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e  UTF-16.</p></li>
16fc0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  .**.** <li><p>  
16fd0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
16fe0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
16ff0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
17000 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
17010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
17020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
17030 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
17040 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
17050 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
17060 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
17070 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  8.</p></li>.** <
17080 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
17090 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
170a0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
170b0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
170c0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
170d0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
170e0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
170f0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
17100 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
17110 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
17120 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
17130 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
17140 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
17150 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
17160 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
17170 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
17180 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
17190 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
171a0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
171b0 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  e it is.** not p
171c0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
171d0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
171e0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
171f0 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a  validated.  .**.
17200 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
17210 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
17220 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
17230 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
17240 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
17250 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
17260 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
17270 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
17280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
17290 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
172a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
172b0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
172c0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
172d0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
172e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
172f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
17300 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
17310 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
17320 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
17330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
17340 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  es16()</li>.**  
17350 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
17360 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
17370 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
17380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
17390 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
173a0 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20  n_blob(),.** or 
173b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
173c0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
173d0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
173e0 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  t into the desir
173f0 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68  ed.** format, th
17400 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
17410 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
17420 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
17430 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a  mn_bytes16() to.
17440 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  ** find the size
17450 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
17460 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
17470 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
17480 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
17490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
174a0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
174b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
174c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41  mn_bytes16().  A
174d0 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78  nd do not.** mix
174e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
174f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
17500 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
17510 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
17520 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
17530 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
17540 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
17550 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
17560 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
17570 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
17580 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
17590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
175a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
175b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
175c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
175d0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
175e0 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
175f0 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
17600 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20  ** and blobs is 
17610 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
17620 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
17630 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
17640 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
17650 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
17660 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
17670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
17680 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a  )], etc. into .*
17690 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
176a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
176b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
176c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
176d0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
176e0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
176f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
17700 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
17710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
17720 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
17730 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
17740 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
17750 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
17760 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
17770 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
17780 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
17790 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
177a0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
177b0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
177c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2f 0a 63 6f 6e  E_NOMEM]..*/.con
177d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
177e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
177f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
17800 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
17810 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
17820 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
17830 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
17840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
17850 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
17860 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
17870 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
17880 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
17890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
178a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
178b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
178c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
178d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
178e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
178f0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
17900 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
17910 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
17920 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
17930 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
17940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
17950 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
17960 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
17970 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
17980 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
179a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
179b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
179c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
179d0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
179e0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
179f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
17a00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17a10 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
17a20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
17a30 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
17a40 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
17a50 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
17a60 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
17a70 65 20 61 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e a .** [sqlite3
17a80 5f 73 74 6d 74 20 7c 20 63 6f 6d 70 69 6c 65 64  _stmt | compiled
17a90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 5d 2e   SQL statement].
17aa0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
17ab0 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
17ac0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
17ad0 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
17ae0 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
17af0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
17b00 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
17b10 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
17b20 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
17b30 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
17b40 45 52 52 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f  ERROR | error co
17b50 64 65 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  de] or [SQLITE_I
17b60 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
17b70 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
17b80 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
17b90 20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75   .**.** This rou
17ba0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
17bb0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
17bc0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
17bd0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
17be0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 76  sqlite3_stmt | v
17bf0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 5d 2e  irtual machine].
17c00 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
17c10 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
17c20 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65   .** completed e
17c30 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
17c40 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
17c50 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
17c60 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
17c70 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
17c80 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28 53  n interrupt.  (S
17c90 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  ee [sqlite3_inte
17ca0 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20 49  rrupt()].) .** I
17cb0 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
17cc0 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
17cd0 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
17ce0 74 69 6f 6e 73 20 63 61 6e 63 65 6c 6c 65 64 2c  tions cancelled,
17cf0 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20    .** depending 
17d00 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
17d10 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a  nces, and the .*
17d20 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  * [SQLITE_ERROR 
17d30 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 72  | result code] r
17d40 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
17d50 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
17d60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
17d70 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
17d80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
17d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
17da0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
17db0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
17dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17dd0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
17de0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
17df0 20 72 65 73 65 74 20 61 20 0a 2a 2a 20 5b 73 71   reset a .** [sq
17e00 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 63 6f 6d  lite3_stmt | com
17e10 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
17e20 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  ent] object..** 
17e30 62 61 63 6b 20 74 6f 20 69 74 27 73 20 69 6e 69  back to it's ini
17e40 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
17e50 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
17e60 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
17e70 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
17e80 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
17e90 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
17ea0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
17eb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
17ec0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
17ed0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
17ee0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
17ef0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
17f00 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
17f10 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
17f20 6e 64 69 6e 67 73 2e 0a 2a 2f 0a 69 6e 74 20 73  ndings..*/.int s
17f30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
17f40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
17f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17f60 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
17f70 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
17f80 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ions.**.** The f
17f90 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
17fa0 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
17fb0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
17fc0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
17fd0 65 73 0a 2a 2a 20 6f 72 20 74 6f 20 72 65 64 65  es.** or to rede
17fe0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
17ff0 72 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  r of existing SQ
18000 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
18010 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 0a  ggregates.  The.
18020 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e  ** difference on
18030 6c 79 20 62 65 74 77 65 65 6e 20 74 68 65 20 74  ly between the t
18040 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
18050 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
18060 20 74 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   the.** name of 
18070 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
18080 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
18090 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
180a0 6e 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  n UTF-8 for.** s
180b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
180c0 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
180d0 2d 31 36 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  -16 for sqlite3_
180e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
180f0 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  6()..**.** The f
18100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 20 7c 20   the [sqlite3 | 
18120 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 5d  database handle]
18130 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 0a   that holds the.
18140 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
18150 6f 72 20 61 67 67 72 65 67 61 74 65 20 69 73 20  or aggregate is 
18160 74 6f 20 62 65 20 61 64 64 65 64 20 6f 72 20 72  to be added or r
18170 65 64 65 66 69 6e 65 64 2e 20 49 66 20 61 20 73  edefined. If a s
18180 69 6e 67 6c 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  ingle.** program
18190 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
181a0 6f 6e 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  one database han
181b0 64 6c 65 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  dle internally, 
181c0 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  then SQL.** func
181d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
181e0 74 65 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  tes must be adde
181f0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
18200 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 0a  o each database.
18210 2a 2a 20 68 61 6e 64 6c 65 20 77 69 74 68 20 77  ** handle with w
18220 68 69 63 68 20 74 68 65 79 20 77 69 6c 6c 20 62  hich they will b
18230 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
18240 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18250 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
18260 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
18270 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
18280 0a 2a 2a 20 6f 72 20 72 65 64 65 66 69 6e 65 64  .** or redefined
18290 2e 0a 2a 2a 20 54 68 65 20 6c 65 6e 67 74 68 20  ..** The length 
182a0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
182b0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
182c0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
182d0 66 20 74 68 65 20 0a 2a 2a 20 7a 65 72 6f 2d 74  f the .** zero-t
182e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
182f0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
18300 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
18310 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
18320 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
18330 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
18340 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
18350 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
18360 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
18370 69 6e 20 61 6e 20 53 51 4c 49 54 45 5f 45 52 52  in an SQLITE_ERR
18380 4f 52 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  OR error..**.** 
18390 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
183a0 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ter is the numbe
183b0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
183c0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
183d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
183e0 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74  gate takes. If t
183f0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
18400 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
18410 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
18420 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
18430 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
18440 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
18450 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  s..**.** The fou
18460 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
18470 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
18480 65 73 20 77 68 61 74 20 0a 2a 2a 20 5b 53 51 4c  es what .** [SQL
18490 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
184a0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
184b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
184c0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
184d0 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
184e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
184f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
18500 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
18510 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
18520 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
18530 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
18540 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
18550 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
18560 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
18570 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
18580 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
18590 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
185a0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
185b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
185c0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
185d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
185e0 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
185f0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
18600 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
18610 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
18620 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
18630 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
18640 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
18650 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
18660 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
18670 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
18680 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
18690 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
186a0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
186b0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
186c0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
186d0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
186e0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
186f0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
18700 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 0a 2a   not care what.*
18710 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  * text encoding 
18720 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
18730 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
18740 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 5b  t should be.** [
18750 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
18760 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
18770 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
18780 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
18790 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
187a0 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 66 75  ion.** of the fu
187b0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
187c0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
187d0 6f 69 6e 74 65 72 20 75 73 69 6e 67 0a 2a 2a 20  ointer using.** 
187e0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
187f0 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ta()]..**.** The
18800 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
18810 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
18820 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
18830 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
18840 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
18850 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
18860 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
18870 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 0a 2a  lement the SQL.*
18880 2a 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  * function or ag
18890 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61  gregate. A scala
188a0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
188b0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
188c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mentation of.** 
188d0 74 68 65 20 78 46 75 6e 63 20 63 61 6c 6c 62 61  the xFunc callba
188e0 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f  ck only, NULL po
188f0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
18900 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
18910 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
18920 61 6c 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41  al parameters. A
18930 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
18940 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
18950 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
18960 69 6f 6e 0a 2a 2a 20 6f 66 20 78 53 74 65 70 20  ion.** of xStep 
18970 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
18980 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
18990 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
189a0 54 6f 20 64 65 6c 65 74 65 20 61 6e 0a 2a 2a 20  To delete an.** 
189b0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
189c0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
189d0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
189e0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
189f0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
18a00 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
18a10 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
18a20 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
18a30 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
18a40 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
18a50 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
18a60 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
18a70 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
18a80 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
18a90 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
18aa0 66 66 65 72 69 6e 67 20 70 65 72 66 65 72 72 65  ffering perferre
18ab0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
18ac0 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
18ad0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
18ae0 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
18af0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
18b00 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
18b10 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
18b20 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2f 0a 69  on is used..*/.i
18b30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
18b40 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
18b50 6c 69 74 65 33 20 2a 2c 0a 20 20 63 6f 6e 73 74  lite3 *,.  const
18b60 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
18b70 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
18b80 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
18b90 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69  ,.  void*,.  voi
18ba0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
18bb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
18bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
18bd0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
18be0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
18bf0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
18c00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
18c10 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
18c20 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
18c30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
18c40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
18c50 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73  sqlite3*,.  cons
18c60 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
18c70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
18c80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
18c90 70 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  p,.  void*,.  vo
18ca0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
18cb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
18cc0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
18cd0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
18ce0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
18cf0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
18d00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
18d10 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
18d20 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
18d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18d40 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
18d50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
18d60 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
18d70 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
18d80 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
18d90 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
18da0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
18db0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
18dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18dd0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
18de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18df0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
18e00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18e10 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
18e20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
18e30 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
18e40 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
18e50 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
18e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
18e70 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
18e80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
18e90 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
18ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18eb0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
18ec0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
18ed0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
18ee0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
18ef0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73 6f  * CAPI3REF: Obso
18f00 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  lete Functions.*
18f10 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
18f20 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77  ions are all now
18f30 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f   obsolete.  In o
18f40 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
18f50 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
18f60 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
18f70 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65 20   older code, we 
18f80 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70 70  continue to supp
18f90 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e  ort.** these fun
18fa0 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72  ctions.  However
18fb0 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e  , new developmen
18fc0 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c  t projects shoul
18fd0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
18fe0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
18ff0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
19000 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
19010 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
19020 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
19030 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
19040 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
19050 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a   want they do..*
19060 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  /.int sqlite3_ag
19070 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
19080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
19090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70  .int sqlite3_exp
190a0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
190b0 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
190c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
190d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
190e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
190f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  ;.int sqlite3_gl
19100 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
19110 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  d);.void sqlite3
19120 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
19130 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
19140 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
19150 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
19160 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
19170 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
19180 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
19190 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
191a0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
191b0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
191c0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
191d0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
191e0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
191f0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
19200 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
19210 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
19220 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
19230 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
19240 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
19250 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
19260 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
19270 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
19280 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
19290 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
192a0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
192b0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
192c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
192d0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
192e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
192f0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
19300 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
19310 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
19320 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
19330 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
19340 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
19350 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
19360 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
19370 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
19380 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
19390 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
193a0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
193b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
193c0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
193d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
193e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
193f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
19400 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
19410 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
19420 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
19430 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
19440 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
19450 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
19460 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
19470 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  ding .** [sqlite
19480 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c 20  3_column_blob | 
19490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
194a0 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65 70   routines] excep
194b0 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73 65  t that .** these
194c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
194d0 20 73 69 6e 67 6c 65 20 5b 73 71 6c 69 74 65 33   single [sqlite3
194e0 5f 76 61 6c 75 65 2a 5d 20 70 6f 69 6e 74 65 72  _value*] pointer
194f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
19500 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  n [sqlite3_stmt*
19510 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
19520 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
19530 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
19540 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
19550 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
19560 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
19570 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
19580 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19590 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
195a0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
195b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
195c0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
195d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
195e0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
195f0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
19600 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
19610 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
19620 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
19630 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
19640 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
19650 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
19660 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
19670 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
19680 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
19690 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
196a0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
196b0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
196c0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
196d0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
196e0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
196f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
19700 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
19710 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
19720 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
19730 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
19740 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 77 6f 72 64  in order.** word
19750 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
19760 73 20 6f 72 69 67 69 6e 61 6c 20 61 20 73 74 72  s original a str
19770 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
19780 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
19790 20 74 68 65 6e 20 69 74 20 69 73 20 64 6f 6e 65   then it is done
197a0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
197b0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
197c0 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b 53 51 4c  s.  The .** [SQL
197d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
197e0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
197f0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
19800 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
19810 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
19820 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
19830 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
19840 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
19850 20 69 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f   is returned fro
19860 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
19870 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
19880 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
19890 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
198a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
198b0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
198c0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
198d0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
198e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
198f0 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
19900 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
19910 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
19920 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
19930 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
19940 74 65 78 74 31 36 28 29 5d 2e 20 20 0a 2a 2a 0a  text16()].  .**.
19950 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19960 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
19970 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
19980 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
19990 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
199a0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 73  t supplied the s
199b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 20 70 61  qlite3_value* pa
199c0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 20 4f 72 2c  rameters..** Or,
199d0 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
199e0 76 61 6c 75 65 2a 20 61 72 67 75 6d 65 6e 74 20  value* argument 
199f0 63 6f 6d 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  comes from the [
19a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
19a10 61 6c 75 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  alue()].** inter
19a20 66 61 63 65 2c 20 74 68 65 6e 20 74 68 65 73 65  face, then these
19a30 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
19a40 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
19a50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 0a  the same thread.
19a60 2a 2a 20 74 68 61 74 20 72 61 6e 20 5b 73 71 6c  ** that ran [sql
19a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
19a80 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  e()]..*/.const v
19a90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
19aa0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
19ab0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
19ac0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
19ad0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
19ae0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
19af0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
19b00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
19b10 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
19b20 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
19b30 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
19b40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
19b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
19b60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
19b70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
19b80 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
19b90 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
19ba0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
19bb0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
19bc0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
19bd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
19be0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
19bf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
19c00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
19c10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
19c20 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
19c30 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
19c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
19c50 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
19c60 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
19c70 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
19c80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
19c90 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
19ca0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
19cb0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
19cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19cd0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
19ce0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
19cf0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  t.**.** The impl
19d00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
19d10 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
19d20 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
19d30 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
19d40 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
19d50 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
19d60 65 69 72 20 73 74 61 74 65 2e 20 20 54 68 65 20  eir state.  The 
19d70 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
19d80 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 63 61  routine.** is ca
19d90 6c 6c 65 64 20 66 6f 72 20 61 20 70 61 72 74 69  lled for a parti
19da0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
19db0 20 61 20 6e 65 77 20 73 74 72 75 63 74 75 72 65   a new structure
19dc0 20 6f 66 20 73 69 7a 65 20 6e 42 79 74 65 73 0a   of size nBytes.
19dd0 2a 2a 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 2c  ** is allocated,
19de0 20 7a 65 72 6f 65 64 2c 20 61 6e 64 20 72 65 74   zeroed, and ret
19df0 75 72 6e 65 64 2e 20 20 4f 6e 20 73 75 62 73 65  urned.  On subse
19e00 71 75 65 6e 74 20 63 61 6c 6c 73 20 28 66 6f 72  quent calls (for
19e10 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 61 67 67   the.** same agg
19e20 72 65 67 61 74 65 20 69 6e 73 74 61 6e 63 65 29  regate instance)
19e30 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
19e40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
19e50 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
19e60 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 61 67 67 72  n.** of the aggr
19e70 65 67 61 74 65 20 63 61 6e 20 75 73 65 20 74 68  egate can use th
19e80 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
19e90 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
19ea0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  data..**.** The 
19eb0 62 75 66 66 65 72 20 61 6c 6c 6f 63 61 74 65 64  buffer allocated
19ec0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
19ed0 74 69 63 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  tically by SQLit
19ee0 65 20 77 68 61 6e 20 74 68 65 20 61 67 67 72 65  e whan the aggre
19ef0 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
19f00 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
19f10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19f20 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
19f30 6f 70 79 20 6f 66 20 74 68 65 20 0a 2a 2a 20 5b  opy of the .** [
19f40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
19f50 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
19f60 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
19f70 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
19f80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
19f90 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
19fa0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
19fb0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
19fc0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19fd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
19fe0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
19ff0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
1a000 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
1a010 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
1a020 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1a030 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
1a040 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1a050 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
1a060 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
1a070 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
1a080 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
1a090 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
1a0a0 2a 0a 2a 2a 20 54 68 65 20 70 55 73 65 72 44 61  *.** The pUserDa
1a0b0 74 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ta parameter to 
1a0c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
1a0d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
1a0e0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
1a0f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
1a100 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  6()] routines.**
1a110 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
1a120 72 20 75 73 65 72 20 66 75 6e 63 74 69 6f 6e 73  r user functions
1a130 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f   is available to
1a140 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
1a150 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 75  tation of the fu
1a160 6e 63 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 69  nction using thi
1a170 73 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s call..**.** Th
1a180 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
1a190 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
1a1a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
1a1b0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
1a1c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
1a1d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
1a1e0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
1a1f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
1a200 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
1a210 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
1a220 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
1a230 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
1a240 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
1a250 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
1a260 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
1a270 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
1a280 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
1a290 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
1a2a0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
1a2b0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
1a2c0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
1a2d0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
1a2e0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
1a2f0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
1a300 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
1a310 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
1a320 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
1a330 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74  ociated meta-dat
1a340 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
1a350 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
1a360 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
1a370 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
1a380 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
1a390 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
1a3a0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
1a3b0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
1a3c0 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
1a3d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
1a3e0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
1a3f0 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74  ta-data associat
1a400 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
1a410 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
1a420 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
1a430 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
1a440 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
1a450 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
1a460 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
1a470 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
1a480 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1a490 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
1a4a0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
1a4b0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
1a4c0 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
1a4d0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
1a4e0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
1a4f0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
1a500 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1a510 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
1a520 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
1a530 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
1a540 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f  eta-data.** asso
1a550 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1a560 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  Nth argument val
1a570 75 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ue to the curren
1a580 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  t SQL function.*
1a590 2a 20 63 61 6c 6c 2c 20 77 68 65 72 65 20 4e 20  * call, where N 
1a5a0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
1a5b0 72 61 6d 65 74 65 72 2e 20 49 66 20 6e 6f 20 6d  rameter. If no m
1a5c0 65 74 61 2d 64 61 74 61 20 68 61 73 20 62 65 65  eta-data has bee
1a5d0 6e 20 73 65 74 20 66 6f 72 0a 2a 2a 20 74 68 61  n set for.** tha
1a5e0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 20  t value, then a 
1a5f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1a600 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1a610 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
1a620 61 75 78 64 61 74 61 28 29 20 69 73 20 75 73 65  auxdata() is use
1a630 64 20 74 6f 20 61 73 73 6f 63 69 61 74 65 20 6d  d to associate m
1a640 65 74 61 2d 64 61 74 61 20 77 69 74 68 20 61 6e  eta-data with an
1a650 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
1a660 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 74   argument. The t
1a670 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1a680 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1a690 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a 2a 20  he meta-data.** 
1a6a0 74 6f 20 62 65 20 61 73 73 6f 63 69 61 74 65 64  to be associated
1a6b0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 75 73   with the Nth us
1a6c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  er function argu
1a6d0 6d 65 6e 74 20 76 61 6c 75 65 2e 20 54 68 65 20  ment value. The 
1a6e0 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65  fourth.** parame
1a6f0 74 65 72 20 73 70 65 63 69 66 69 65 73 20 61 20  ter specifies a 
1a700 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
1a710 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6f  will be called o
1a720 6e 20 74 68 65 20 6d 65 74 61 2d 0a 2a 2a 20 64  n the meta-.** d
1a730 61 74 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 72  ata pointer to r
1a740 65 6c 65 61 73 65 20 69 74 20 77 68 65 6e 20 69  elease it when i
1a750 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1a760 65 71 75 69 72 65 64 2e 20 49 66 20 74 68 65 20  equired. If the 
1a770 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 69  .** destructor i
1a780 73 20 4e 55 4c 4c 2c 20 69 74 20 69 73 20 6e 6f  s NULL, it is no
1a790 74 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  t invoked..**.**
1a7a0 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
1a7b0 74 61 2d 64 61 74 61 20 69 73 20 70 72 65 73 65  ta-data is prese
1a7c0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
1a7d0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
1a7e0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
1a7f0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
1a800 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1a810 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
1a820 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
1a830 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
1a840 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
1a850 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
1a860 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
1a870 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
1a880 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
1a890 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
1a8a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
1a8b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1a8c0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
1a8d0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
1a8e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
1a8f0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
1a900 74 65 78 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  text*, int, void
1a910 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
1a920 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
1a930 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
1a940 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
1a950 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
1a960 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
1a970 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
1a980 6c 75 65 20 66 6f 72 20 74 68 65 20 64 65 73 74  lue for the dest
1a990 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
1a9a0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
1a9b0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
1a9c0 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
1a9d0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
1a9e0 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
1a9f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
1aa00 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
1aa10 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
1aa20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
1aa30 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
1aa40 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
1aa50 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
1aa60 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
1aa70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
1aa80 74 72 6f 79 65 64 2e 20 20 54 68 65 20 0a 2a 2a  troyed.  The .**
1aa90 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
1aaa0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
1aab0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
1aac0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
1aad0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
1aae0 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
1aaf0 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
1ab00 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
1ab10 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
1ab20 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
1ab30 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
1ab40 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
1ab50 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
1ab60 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
1ab70 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
1ab80 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
1ab90 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31    See ticket #21
1aba0 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76  91..*/.typedef v
1abb0 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65  oid (*sqlite3_de
1abc0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76  structor_type)(v
1abd0 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53  oid*);.#define S
1abe0 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20  QLITE_STATIC    
1abf0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
1ac00 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23  ructor_type)0).#
1ac10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1ac20 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69  ANSIENT   ((sqli
1ac30 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
1ac40 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43  ype)-1)../*.** C
1ac50 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67  API3REF: Setting
1ac60 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41   The Result Of A
1ac70 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a  n SQL Function.*
1ac80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ac90 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
1aca0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
1acb0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
1acc0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
1acd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
1ace0 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
1acf0 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
1ad00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1ad10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
1ad20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
1ad30 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
1ad40 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1ad50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
1ad60 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
1ad70 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
1ad80 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
1ad90 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
1ada0 33 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79  3_bind_*] family
1adb0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73   of functions us
1adc0 65 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61  ed.** to bind va
1add0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
1ade0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
1adf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
1ae00 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a  ** Refer to the.
1ae10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ae20 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1ae30 62 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61  bind_* documenta
1ae40 74 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64  tion] for.** add
1ae50 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
1ae60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
1ae70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1ae80 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
1ae90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
1aea0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
1aeb0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
1aec0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
1aed0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
1aee0 78 63 65 70 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  xception.  The.*
1aef0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  * parameter to s
1af00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1af10 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
1af20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
1af30 29 0a 2a 2a 20 69 73 20 74 68 65 20 74 65 78 74  ).** is the text
1af40 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
1af50 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sage..**.** The 
1af60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
1af70 6f 6f 62 69 67 28 29 20 63 61 75 73 65 20 74 68  oobig() cause th
1af80 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
1af90 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  mentation.** to 
1afa0 74 68 72 6f 77 20 61 6e 64 20 65 72 72 6f 72 20  throw and error 
1afb0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
1afc0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
1afd0 20 69 73 20 74 6f 20 6c 6f 6e 67 0a 2a 2a 20 74   is to long.** t
1afe0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
1aff0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b000 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
1b010 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
1b020 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
1b030 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
1b040 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
1b050 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
1b060 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
1b070 72 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  r..*/.void sqlit
1b080 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
1b090 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b0a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1b0b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1b0c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
1b0d0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
1b0e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
1b0f0 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
1b100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b110 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
1b120 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
1b130 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1b140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
1b150 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
1b160 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1b170 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
1b180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
1b190 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
1b1a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
1b1b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
1b1c0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
1b1d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
1b1e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b1f0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
1b200 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
1b210 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
1b220 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
1b230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
1b240 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
1b250 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
1b260 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
1b270 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
1b280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
1b290 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
1b2a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
1b2b0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1b2c0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1b2d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1b2e0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
1b2f0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
1b300 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1b310 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
1b320 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
1b330 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
1b340 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
1b350 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
1b360 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
1b370 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
1b380 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
1b390 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
1b3a0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
1b3b0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
1b3c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1b3d0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
1b3e0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
1b3f0 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
1b400 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
1b410 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
1b420 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
1b430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1b440 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
1b450 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
1b460 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
1b470 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
1b480 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
1b490 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
1b4a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20  e.** [sqlite3*] 
1b4b0 68 61 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64  handle specified
1b4c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
1b4d0 67 75 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54  gument. .**.** T
1b4e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
1b4f0 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ew collation seq
1b500 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69  uence is specifi
1b510 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74  ed as a UTF-8 st
1b520 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
1b530 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1b540 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
1b550 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1b560 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
1b570 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
1b580 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
1b590 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
1b5a0 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a  .  In all cases.
1b5b0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70  ** the name is p
1b5c0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
1b5d0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
1b5e0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
1b5f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1b600 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  may be one of th
1b610 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
1b620 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53  ITE_UTF8],.** [S
1b630 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f  QLITE_UTF16LE] o
1b640 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
1b650 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
1b660 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75 70  hat the user-sup
1b670 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65  plied.** routine
1b680 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20 70   expects to be p
1b690 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20 74  assed pointers t
1b6a0 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64 65  o strings encode
1b6b0 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a  d using UTF-8,.*
1b6c0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  * UTF-16 little-
1b6d0 65 6e 64 69 61 6e 20 6f 72 20 55 54 46 2d 31 36  endian or UTF-16
1b6e0 20 62 69 67 2d 65 6e 64 69 61 6e 20 72 65 73 70   big-endian resp
1b6f0 65 63 74 69 76 65 6c 79 2e 20 20 54 68 65 0a 2a  ectively.  The.*
1b700 2a 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  * third argument
1b710 20 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b   might also be [
1b720 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
1b730 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74  GNED] to indicat
1b740 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f  e that.** the ro
1b750 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f  utine expects po
1b760 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74  inters to 16-bit
1b770 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74   word aligned st
1b780 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 31  rings.** of UTF1
1b790 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1b7a0 62 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68  byte order of th
1b7b0 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
1b7c0 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
1b7d0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
1b7e0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
1b7f0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
1b800 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
1b810 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 69 73 20  ument. If it is 
1b820 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68  NULL, this is th
1b830 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69  e same as deleti
1b840 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ng the collation
1b850 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f  .** sequence (so
1b860 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
1b870 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d  not call it anym
1b880 6f 72 65 29 2e 20 45 61 63 68 20 74 69 6d 65 20  ore). Each time 
1b890 74 68 65 20 75 73 65 72 0a 2a 2a 20 73 75 70 70  the user.** supp
1b8a0 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  lied function is
1b8b0 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20   invoked, it is 
1b8c0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
1b8d0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
1b8e0 64 20 61 73 0a 2a 2a 20 74 68 65 20 66 6f 75 72  d as.** the four
1b8f0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1b900 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1b910 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 0a 2a 2a 20  llation() or.** 
1b920 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1b930 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 20 61 73 20  ollation16() as 
1b940 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
1b950 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  ter..**.** The r
1b960 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
1b970 74 73 20 74 6f 20 74 68 65 20 75 73 65 72 2d 73  ts to the user-s
1b980 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
1b990 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
1b9a0 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
1b9b0 6e 74 65 64 20 62 79 20 61 20 5b 6c 65 6e 67 74  nted by a [lengt
1b9c0 68 2c 20 64 61 74 61 5d 20 70 61 69 72 20 61 6e  h, data] pair an
1b9d0 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
1b9e0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
1b9f0 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
1ba00 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1ba10 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
1ba20 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
1ba30 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
1ba40 2e 20 54 68 65 20 75 73 65 72 20 72 6f 75 74 69  . The user routi
1ba50 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ne should return
1ba60 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
1ba70 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a  or positive if.*
1ba80 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  * the first stri
1ba90 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
1baa0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
1bab0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
1bac0 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e  econd.** string.
1bad0 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
1bae0 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
1baf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
1bb00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
1bb10 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
1bb20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
1bb30 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 61  lation().** exca
1bb40 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
1bb50 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
1bb60 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
1bb70 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
1bb80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
1bb90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
1bba0 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
1bbb0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
1bbc0 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
1bbd0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
1bbe0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
1bbf0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
1bc00 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
1bc10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
1bc20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 20  collation_v2(). 
1bc30 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20   Collations are 
1bc40 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 0a 2a  destroyed when.*
1bc50 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  * they are overr
1bc60 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
1bc70 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
1bc80 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
1bc90 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72 20 77  unctions.** or w
1bca0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1bcb0 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  *] database hand
1bcc0 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  le is closed usi
1bcd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
1bce0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  e()]..**.** The 
1bcf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
1bd00 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 69 6e  ollation_v2() in
1bd10 74 65 72 66 61 63 65 20 69 73 20 65 78 70 65 72  terface is exper
1bd20 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 73  imental and.** s
1bd30 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1bd40 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1bd50 73 65 73 2e 20 20 54 68 65 20 6f 74 68 65 72 20  ses.  The other 
1bd60 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
1bd70 6f 6e 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  on.** functions 
1bd80 61 72 65 20 73 74 61 62 6c 65 2e 0a 2a 2f 0a 69  are stable..*/.i
1bd90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
1bda0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
1bdb0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
1bdc0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
1bdd0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
1bde0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
1bdf0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
1be00 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1be10 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
1be20 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
1be30 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1be40 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
1be50 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
1be60 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
1be70 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
1be80 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
1be90 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
1bea0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
1beb0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
1bec0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
1bed0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
1bee0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
1bef0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
1bf00 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
1bf10 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
1bf20 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
1bf30 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
1bf40 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
1bf50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
1bf60 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
1bf70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bf80 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
1bf90 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
1bfa0 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
1bfb0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
1bfc0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
1bfd0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
1bfe0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
1bff0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
1c000 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1c010 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
1c020 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
1c030 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
1c040 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
1c050 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
1c060 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
1c070 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71  quence is.** req
1c080 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
1c090 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
1c0a0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
1c0b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
1c0c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
1c0d0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
1c0e0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
1c0f0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
1c100 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
1c110 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
1c120 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
1c130 46 2d 38 2e 20 49 66 20 73 71 6c 69 74 65 33 5f  F-8. If sqlite3_
1c140 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
1c150 31 36 28 29 20 69 73 20 75 73 65 64 2c 20 74 68  16() is used, th
1c160 65 20 6e 61 6d 65 73 0a 2a 2a 20 61 72 65 20 70  e names.** are p
1c170 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
1c180 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
1c190 65 20 62 79 74 65 20 6f 72 64 65 72 2e 20 41 20  e byte order. A 
1c1a0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 0a 2a  call to either.*
1c1b0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  * function repla
1c1c0 63 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67  ces any existing
1c1d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
1c1e0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1c1f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
1c200 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1c210 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
1c220 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
1c230 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
1c240 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
1c250 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
1c260 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
1c270 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 54  on_needed16(). T
1c280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1c290 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
1c2a0 73 65 0a 2a 2a 20 68 61 6e 64 6c 65 2e 20 54 68  se.** handle. Th
1c2b0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1c2c0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
1c2d0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
1c2e0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 0a 2a  E_UTF16BE], or.*
1c2f0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
1c300 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
1c310 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
1c320 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
1c330 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
1c340 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
1c350 75 69 72 65 64 2e 20 54 68 65 20 66 6f 75 72 74  uired. The fourt
1c360 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
1c370 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1c380 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
1c390 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
1c3a0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
1c3b0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
1c3c0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
1c3d0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
1c3e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1c3f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
1c400 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
1c410 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
1c420 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
1c430 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
1c440 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
1c450 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1c460 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
1c470 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
1c480 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
1c490 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
1c4a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
1c4b0 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
1c4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
1c4d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
1c4e0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
1c4f0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
1c500 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
1c510 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
1c520 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
1c530 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
1c540 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
1c550 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
1c560 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
1c570 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
1c580 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
1c590 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
1c5a0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
1c5b0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
1c5c0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
1c5d0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
1c5e0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
1c5f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1c600 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
1c610 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1c620 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1c630 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
1c640 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
1c650 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
1c660 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
1c670 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
1c680 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
1c690 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
1c6a0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
1c6b0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
1c6c0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
1c6d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
1c6e0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
1c6f0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
1c700 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
1c710 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
1c720 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
1c730 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
1c740 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
1c750 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
1c760 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
1c770 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
1c780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
1c790 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
1c7a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
1c7b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1c7c0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
1c7d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1c7e0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
1c7f0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
1c800 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
1c810 41 50 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e  API3REF:  Suspen
1c820 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
1c830 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
1c840 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1c850 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
1c860 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
1c870 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
1c880 2a 2a 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  ** a number of m
1c890 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
1c8a0 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
1c8b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
1c8c0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1c8d0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
1c8e0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
1c8f0 75 65 73 74 73 20 77 69 74 68 20 0a 2a 2a 20 6d  uests with .** m
1c900 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
1c910 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
1c920 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
1c930 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 20  e rounded up to 
1c940 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
1c950 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
1c960 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
1c970 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
1c980 61 6c 6c 79 20 0a 2a 2a 20 72 65 71 75 65 73 74  ally .** request
1c990 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
1c9a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
1c9b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c9c0 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
1c9d0 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
1c9e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
1c9f0 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
1ca00 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1ca10 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1ca20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
1ca30 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
1ca40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ca50 45 46 3a 20 20 4e 61 6d 65 20 4f 66 20 54 68 65  EF:  Name Of The
1ca60 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
1ca70 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
1ca80 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
1ca90 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
1caa0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1cab0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
1cac0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
1cad0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
1cae0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
1caf0 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
1cb00 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
1cb10 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
1cb20 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
1cb30 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
1cb40 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
1cb50 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  .** is NULL poin
1cb60 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
1cb70 20 64 6f 65 73 20 61 20 73 65 61 72 63 68 20 66   does a search f
1cb80 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
1cb90 65 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66  e temporary.** f
1cba0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
1cbb0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
1cbc0 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
1cbd0 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
1cbe0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1cbf0 65 63 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65  ection.** has be
1cc00 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69  en opened.  It i
1cc10 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
1cc20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
1cc30 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
1cc40 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
1cc50 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
1cc60 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
1cc70 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
1cc80 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
1cc90 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65  been call and re
1cca0 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74  main unchanged t
1ccb0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51  hereafter..*/.SQ
1ccc0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
1ccd0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
1cce0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
1ccf0 20 43 41 50 49 33 52 45 46 3a 20 20 54 65 73 74   CAPI3REF:  Test
1cd00 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 44   To See If The D
1cd10 61 74 61 62 61 73 65 20 49 73 20 49 6e 20 41 75  atabase Is In Au
1cd20 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
1cd30 2a 0a 2a 2a 20 54 65 73 74 20 74 6f 20 73 65 65  *.** Test to see
1cd40 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1cd50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cd60 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 61 75  nection is in au
1cd70 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 6d 6f 64 65  tocommit.** mode
1cd80 2e 20 20 52 65 74 75 72 6e 20 54 52 55 45 20 69  .  Return TRUE i
1cd90 66 20 69 74 20 69 73 20 61 6e 64 20 46 41 4c 53  f it is and FALS
1cda0 45 20 69 66 20 6e 6f 74 2e 20 20 41 75 74 6f 63  E if not.  Autoc
1cdb0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
1cdc0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20  .** by default. 
1cdd0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 69 73 20 64   Autocommit is d
1cde0 69 73 61 62 6c 65 64 20 62 79 20 61 20 42 45 47  isabled by a BEG
1cdf0 49 4e 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  IN statement and
1ce00 20 72 65 65 6e 61 62 6c 65 64 0a 2a 2a 20 62 79   reenabled.** by
1ce10 20 74 68 65 20 6e 65 78 74 20 43 4f 4d 4d 49 54   the next COMMIT
1ce20 20 6f 72 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a   or ROLLBACK..**
1ce30 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
1ce40 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
1ce50 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
1ce60 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
1ce70 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
1ce80 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72  transactions (er
1ce90 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
1cea0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
1ceb0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a  QLITE_IOERR], .*
1cec0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
1ced0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
1cee0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
1cef0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
1cf00 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
1cf10 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
1cf20 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
1cf30 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
1cf40 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
1cf50 74 20 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f  t if SQLite auto
1cf60 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
1cf70 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
1cf80 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
1cf90 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
1cfa0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
1cfb0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
1cfc0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
1cfd0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
1cfe0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
1cff0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
1d000 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
1d010 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
1d020 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
1d030 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
1d040 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
1d050 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
1d060 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
1d070 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1d080 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65 20 44  REF:  Find The D
1d090 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 41  atabase Handle A
1d0a0 73 73 6f 63 69 61 74 65 64 20 57 69 74 68 20 41  ssociated With A
1d0b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1d0c0 65 6e 74 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  ent.**.** Return
1d0d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a 5d 20   the [sqlite3*] 
1d0e0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
1d0f0 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20 5b 73  to which a.** [s
1d100 71 6c 69 74 65 33 5f 73 74 6d 74 20 7c 20 70 72  qlite3_stmt | pr
1d110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d120 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a 20 54 68  ] belongs..** Th
1d130 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  is is the same d
1d140 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
1d150 68 61 74 20 77 61 73 0a 2a 2a 20 74 68 65 20 66  hat was.** the f
1d160 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d170 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1d180 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1d190 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 74  ts variants.** t
1d1a0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 20  hat was used to 
1d1b0 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
1d1c0 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
1d1d0 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69  t place..*/.sqli
1d1e0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
1d1f0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
1d200 74 6d 74 2a 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  tmt*);.../*.** C
1d210 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
1d220 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
1d230 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
1d240 63 6b 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  cks.**.** These 
1d250 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 67 69  routines.** regi
1d260 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1d270 6e 63 74 69 6f 6e 73 20 74 6f 20 62 65 20 69 6e  nctions to be in
1d280 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
1d290 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1d2a0 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20  is committed or 
1d2b0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 20 20 54 68  rolled back.  Th
1d2c0 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
1d2d0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1d2e0 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  h.** to the call
1d2f0 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63 61  back.  If the ca
1d300 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
1d310 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
1d320 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e   .** returns non
1d330 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
1d340 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
1d350 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
1d360 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
1d370 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
1d380 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
1d390 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
1d3a0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
1d3b0 72 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  rned..** Otherwi
1d3c0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
1d3d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  ned..**.** Regis
1d3e0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
1d3f0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
1d400 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
1d410 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
1d420 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
1d430 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
1d440 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
1d450 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20  been .** rolled 
1d460 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
1d470 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
1d480 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
1d490 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
1d4a0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
1d4b0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
1d4c0 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
1d4d0 6f 20 6f 63 63 75 72 2e 20 54 68 65 20 0a 2a 2a  o occur. The .**
1d4e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
1d4f0 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
1d500 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
1d510 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
1d520 64 0a 2a 2a 20 62 61 63 6b 20 62 65 63 61 75 73  d.** back becaus
1d530 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1d540 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1d550 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1d560 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e 74 61   are experimenta
1d570 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 6e 64  l interfaces and
1d580 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
1d590 63 68 61 6e 67 65 2e 0a 2a 2f 0a 76 6f 69 64 20  change..*/.void 
1d5a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
1d5b0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
1d5c0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1d5d0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
1d5e0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
1d5f0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
1d600 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
1d610 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d620 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
1d630 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
1d640 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 52  allbacks.**.** R
1d650 65 67 69 73 74 65 72 20 61 20 63 61 6c 6c 62 61  egister a callba
1d660 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ck function with
1d670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d680 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66  nnection identif
1d690 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1d6a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1d6b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
1d6c0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
1d6d0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
1d6e0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
1d6f0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
1d700 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
1d710 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
1d720 69 6f 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ion for the same
1d730 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f   .** database co
1d740 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
1d750 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ridden..**.** Th
1d760 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1d770 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
1d780 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
1d790 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20  o invoke when a 
1d7a0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
1d7b0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
1d7c0 64 65 6c 65 74 65 64 2e 20 54 68 65 20 66 69 72  deleted. The fir
1d7d0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1d7e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a  he callback is.*
1d7f0 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  * a copy of the 
1d800 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1d810 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
1d820 5f 68 6f 6f 6b 28 29 2e 20 54 68 65 20 73 65 63  _hook(). The sec
1d830 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a  ond callback .**
1d840 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
1d850 20 6f 66 20 53 51 4c 49 54 45 5f 49 4e 53 45 52   of SQLITE_INSER
1d860 54 2c 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  T, SQLITE_DELETE
1d870 20 6f 72 20 53 51 4c 49 54 45 5f 55 50 44 41 54   or SQLITE_UPDAT
1d880 45 2c 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  E, depending.** 
1d890 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
1d8a0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
1d8b0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
1d8c0 69 6e 76 6f 6b 65 64 2e 20 54 68 65 20 74 68 69  invoked. The thi
1d8d0 72 64 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74  rd and .** fourt
1d8e0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
1d8f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
1d900 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
1d910 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1d920 20 0a 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20   .** table name 
1d930 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
1d940 66 66 65 63 74 65 64 20 72 6f 77 2e 20 54 68 65  ffected row. The
1d950 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
1d960 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a 2a  parameter is .**
1d970 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
1d980 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61  e row. In the ca
1d990 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
1d9a0 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f 77   this is the row
1d9b0 69 64 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65  id after .** the
1d9c0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
1d9d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
1d9e0 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
1d9f0 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
1da00 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
1da10 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
1da20 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
1da30 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
1da40 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
1da50 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
1da60 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
1da70 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
1da80 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
1da90 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
1daa0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 20 4e 55  .** Otherwise NU
1dab0 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
1dac0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1dad0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
1dae0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
1daf0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
1db00 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
1db10 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
1db20 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
1db30 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
1db40 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20 4f  I3REF:  Enable O
1db50 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
1db60 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 0a   Pager Cache.**.
1db70 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
1db80 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1db90 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
1dba0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1dbb0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
1dbc0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
1dbd0 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e  res between conn
1dbe0 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73  ections to the s
1dbf0 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  ame database..**
1dc00 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
1dc10 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
1dc20 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20  ent is true and 
1dc30 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
1dc40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66  argument.** is f
1dc50 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 42 65 67 69  alse..**.** Begi
1dc60 6e 6e 69 6e 67 20 69 6e 20 53 51 4c 69 74 65 20  nning in SQLite 
1dc70 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 63  version 3.5.0, c
1dc80 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
1dc90 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
1dca0 62 6c 65 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65  bled.** for an e
1dcb0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 20  ntire process.  
1dcc0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
1dcd0 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73 68 61  s of SQLite, sha
1dce0 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ring was.** enab
1dcf0 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
1dd00 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
1dd10 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
1dd20 2a 20 54 68 65 20 63 61 63 68 65 20 73 68 61 72  * The cache shar
1dd30 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
1dd40 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
1dd50 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
1dd60 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
1dd70 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1dd80 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1dd90 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
1dda0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1ddb0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
1ddc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ddd0 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
1dde0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
1ddf0 74 68 61 74 20 77 61 73 0a 2a 2a 20 69 6e 20 65  that was.** in e
1de00 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
1de10 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
1de20 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ed..**.** Virtua
1de30 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f 74 20  l tables cannot 
1de40 62 65 20 75 73 65 64 20 77 69 74 68 20 61 20 73  be used with a s
1de50 68 61 72 65 64 20 63 61 63 68 65 2e 20 20 57 68  hared cache.  Wh
1de60 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  en shared.** cac
1de70 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
1de80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
1de90 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49  te_module()] API
1dea0 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
1deb0 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  r.** virtual tab
1dec0 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  les will always 
1ded0 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
1dee0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1def0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
1df00 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
1df10 64 20 63 61 63 68 65 20 77 61 73 0a 2a 2a 20 65  d cache was.** e
1df20 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
1df30 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ed successfully.
1df40 20 20 41 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52    An [SQLITE_ERR
1df50 4f 52 20 7c 20 65 72 72 6f 72 20 63 6f 64 65 5d  OR | error code]
1df60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1df70 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
1df80 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73   Shared cache is
1df90 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1dfa0 61 75 6c 74 2e 20 20 42 75 74 20 74 68 69 73 20  ault.  But this 
1dfb0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
1dfc0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
1dfd0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
1dfe0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1dff0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
1e000 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
1e010 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
1e020 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2f  t explicitly..*/
1e030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
1e040 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1e050 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
1e060 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
1e070 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
1e080 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 41 74 74 65 6d  mory.**.** Attem
1e090 70 74 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  pt to free N byt
1e0a0 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  es of heap memor
1e0b0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
1e0c0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a  g non-essential.
1e0d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1e0e0 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
1e0f0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
1e100 72 79 20 28 65 78 61 6d 70 6c 65 3a 20 6d 65 6d  ry (example: mem
1e110 6f 72 79 20 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ory .** used to 
1e120 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20 70  cache database p
1e130 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
1e140 70 65 72 66 6f 72 6d 61 6e 63 65 29 2e 0a 2a 2f  performance)..*/
1e150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
1e160 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
1e170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e180 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
1e190 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
1e1a0 2a 2a 0a 2a 2a 20 50 6c 61 63 65 20 61 20 22 73  **.** Place a "s
1e1b0 6f 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68  oft" limit on th
1e1c0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
1e1d0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
1e1e0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a   be allocated.**
1e1f0 20 62 79 20 53 51 4c 69 74 65 2e 20 20 49 66 20   by SQLite.  If 
1e200 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
1e210 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
1e220 74 65 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75  ted .** that wou
1e230 6c 64 20 65 78 63 65 65 64 20 74 68 65 20 73 70  ld exceed the sp
1e240 65 63 69 66 69 65 64 20 6c 69 6d 69 74 2c 20 5b  ecified limit, [
1e250 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
1e260 6d 65 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20  memory()] is.** 
1e270 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d  invoked one or m
1e280 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
1e290 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
1e2a0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
1e2b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65  ation.** is made
1e2c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69  ..**.** The limi
1e2d0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
1e2e0 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b  t", because if [
1e2f0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
1e300 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f 74  memory()] cannot
1e310 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63 69  .** free suffici
1e320 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72  ent memory to pr
1e330 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20  event the limit 
1e340 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65  from being excee
1e350 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ded,.** the memo
1e360 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
1e370 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63  anyway and the c
1e380 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
1e390 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a   proceeds..**.**
1e3a0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a   A negative or z
1e3b0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
1e3c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
1e3d0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
1e3e0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
1e3f0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
1e400 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
1e410 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
1e420 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
1e430 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65  usted..** The de
1e440 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
1e450 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
1e460 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
1e470 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1e480 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f  a best effort to
1e490 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20   honor the soft 
1e4a0 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 42 75 74  heap limit.  But
1e4b0 20 69 66 20 69 74 0a 2a 2a 20 69 73 20 75 6e 61   if it.** is una
1e4c0 62 6c 65 20 74 6f 20 72 65 64 75 63 65 20 6d 65  ble to reduce me
1e4d0 6d 6f 72 79 20 75 73 61 67 65 20 62 65 6c 6f 77  mory usage below
1e4e0 20 74 68 65 20 73 6f 66 74 20 6c 69 6d 69 74 2c   the soft limit,
1e4f0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
1e500 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
1e510 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
1e520 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
1e530 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
1e540 74 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20  t is .** called 
1e550 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
1e560 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
1e570 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
1e580 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1e590 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
1e5a0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
1e5b0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
1e5c0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
1e5d0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
1e5e0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
1e5f0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
1e600 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
1e610 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
1e620 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
1e630 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
1e640 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
1e650 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
1e660 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20 54 68  all threads.  Th
1e670 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
1e680 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
1e690 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
1e6a0 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
1e6b0 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
1e6c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
1e6d0 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 20  r all threads.  
1e6e0 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
1e6f0 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
1e700 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
1e710 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
1e720 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
1e730 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
1e740 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1e750 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
1e760 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
1e770 50 49 33 52 45 46 3a 20 20 45 78 74 72 61 63 74  PI3REF:  Extract
1e780 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
1e790 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
1e7a0 62 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ble.**.** This r
1e7b0 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e  outine.** return
1e7c0 73 20 6d 65 74 61 2d 64 61 74 61 20 61 62 6f 75  s meta-data abou
1e7d0 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
1e7e0 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
1e7f0 63 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 74 61  c database.** ta
1e800 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
1e810 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
1e820 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61 73 73 65  ion handle passe
1e830 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
1e840 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75  unction .** argu
1e850 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
1e860 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
1e870 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
1e880 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
1e890 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
1e8a0 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  to .** this func
1e8b0 74 69 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64  tion. The second
1e8c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69   parameter is ei
1e8d0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66  ther the name of
1e8e0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1e8f0 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22   (i.e. "main", "
1e900 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61  temp" or an atta
1e910 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
1e920 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
1e930 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
1e940 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20   or NULL. If it 
1e950 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
1e960 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
1e970 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
1e980 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
1e990 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
1e9a0 65 20 61 6c 67 6f 72 69 74 68 6d 20 61 73 20 74  e algorithm as t
1e9b0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
1e9c0 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72  ne uses to .** r
1e9d0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
1e9e0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
1e9f0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ces..**.** The t
1ea00 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
1ea10 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ea20 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
1ea30 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
1ea40 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66  lumn .** name of
1ea50 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
1ea60 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
1ea70 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
1ea80 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 20 0a  ese parameters .
1ea90 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a  ** may be NULL..
1eaa0 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72  **.** Meta infor
1eab0 6d 61 74 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  mation is return
1eac0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
1ead0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
1eae0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 0a  tions passed as.
1eaf0 2a 2a 20 74 68 65 20 35 74 68 20 61 6e 64 20 73  ** the 5th and s
1eb00 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
1eb10 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
1eb20 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68  ction. Any of th
1eb30 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ese .** argument
1eb40 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69  s may be NULL, i
1eb50 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
1eb60 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
1eb70 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a  lement of meta .
1eb80 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1eb90 73 20 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  s ommitted..**.*
1eba0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d  * <pre>.** Param
1ebb0 65 74 65 72 20 20 20 20 20 4f 75 74 70 75 74 20  eter     Output 
1ebc0 54 79 70 65 20 20 20 20 20 20 44 65 73 63 72 69  Type      Descri
1ebd0 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d  ption.** -------
1ebe0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ebf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a  ------------.**.
1ec00 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20 20 20  **   5th        
1ec10 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20   const char*    
1ec20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 20    Data type.**  
1ec30 20 36 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e   6th         con
1ec40 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 4e 61  st char*      Na
1ec50 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  me of the defaul
1ec60 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
1ec70 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68 20 20  ence .**   7th  
1ec80 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20         int      
1ec90 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20          True if 
1eca0 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61  the column has a
1ecb0 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
1ecc0 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20 20 20  aint.**   8th   
1ecd0 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
1ece0 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
1ecf0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  he column is par
1ed00 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
1ed10 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20 20 20   KEY.**   9th   
1ed20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20 20 20        int       
1ed30 20 20 20 20 20 20 20 54 72 75 65 20 69 66 20 74         True if t
1ed40 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41 55 54  he column is AUT
1ed50 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f  OINCREMENT.** </
1ed60 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  pre>.**.**.** Th
1ed70 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
1ed80 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
1ed90 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
1eda0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 20 0a  turned for the .
1edb0 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
1edc0 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
1edd0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
1ede0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
1edf0 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61 6c 6c  he next .** call
1ee00 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65 20 41   to any sqlite A
1ee10 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
1ee20 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63 69 66  ** If the specif
1ee30 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
1ee40 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 74 68  ually a view, th
1ee50 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  en an error is r
1ee60 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
1ee70 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
1ee80 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
1ee90 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
1eea0 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a 2a 2a  wid_" and an .**
1eeb0 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
1eec0 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61 73 20   KEY column has 
1eed0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
1eee0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
1eef0 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20 70 61  he output .** pa
1ef00 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
1ef10 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
1ef20 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
1ef30 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20 69 73  umn. If there is
1ef40 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
1ef50 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b 20 63  y declared IPK c
1ef60 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20  olumn, then the 
1ef70 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74 65 72  output parameter
1ef80 73 20 61 72 65 20 73 65 74 20 61 73 20 0a 2a 2a  s are set as .**
1ef90 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1efa0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
1efb0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
1efc0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
1efd0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
1efe0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
1eff0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
1f000 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
1f010 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
1f020 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
1f030 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
1f040 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
1f050 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
1f060 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
1f070 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
1f080 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
1f090 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
1f0a0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
1f0b0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
1f0c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
1f0d0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 53 51   be found, an SQ
1f0e0 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64 65 20  LITE error code 
1f0f0 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
1f100 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1f110 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68 65 20  .** left in the 
1f120 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
1f130 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
1f140 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
1f150 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20  rrmsg())..**.** 
1f160 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
1f170 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
1f180 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
1f190 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
1f1a0 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
1f1b0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
1f1c0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
1f1d0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
1f1e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
1f1f0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
1f200 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
1f210 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
1f220 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
1f230 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f240 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
1f250 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f260 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
1f270 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f280 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
1f290 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
1f2a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f2b0 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
1f2c0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
1f2d0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
1f2e0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
1f2f0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
1f300 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
1f310 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
1f320 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
1f330 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
1f340 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
1f350 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
1f360 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
1f370 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
1f380 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
1f390 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
1f3a0 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
1f3b0 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
1f3c0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
1f3d0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
1f3e0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
1f3f0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
1f400 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
1f410 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
1f420 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
1f430 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
1f440 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
1f450 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
1f460 0a 2a 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 6c  .** Attempt to l
1f470 6f 61 64 20 61 6e 20 53 51 4c 69 74 65 20 65 78  oad an SQLite ex
1f480 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
1f490 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
1f4a0 20 66 69 6c 65 0a 2a 2a 20 7a 46 69 6c 65 2e 20   file.** zFile. 
1f4b0 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   The entry point
1f4c0 20 69 73 20 7a 50 72 6f 63 2e 20 20 7a 50 72 6f   is zProc.  zPro
1f4d0 63 20 6d 61 79 20 62 65 20 30 20 69 6e 20 77 68  c may be 0 in wh
1f4e0 69 63 68 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  ich case the.** 
1f4f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
1f500 79 20 70 6f 69 6e 74 20 64 65 66 61 75 6c 74 73  y point defaults
1f510 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
1f520 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
1f530 0a 2a 2a 20 52 65 74 75 72 6e 20 5b 53 51 4c 49  .** Return [SQLI
1f540 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
1f550 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
1f560 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
1f570 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
1f580 0a 2a 2a 20 49 66 20 61 6e 20 65 72 72 6f 72 20  .** If an error 
1f590 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
1f5a0 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
1f5b0 65 6e 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  en fill *pzErrMs
1f5c0 67 20 77 69 74 68 20 0a 2a 2a 20 65 72 72 6f 72  g with .** error
1f5d0 20 6d 65 73 73 61 67 65 20 74 65 78 74 2e 20 20   message text.  
1f5e0 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
1f5f0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 72 65 65  tion should free
1f600 20 74 68 69 73 20 6d 65 6d 6f 72 79 0a 2a 2a 20   this memory.** 
1f610 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1f620 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
1f630 2a 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** Extension loa
1f640 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
1f650 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1f660 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
1f670 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
1f680 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1f690 20 74 68 69 73 20 41 50 49 20 6f 72 20 61 6e 20   this API or an 
1f6a0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
1f6b0 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  turned..*/.int s
1f6c0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
1f6d0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
1f6e0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
1f6f0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
1f700 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
1f710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f720 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
1f730 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
1f740 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
1f750 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
1f760 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
1f770 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f780 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
1f790 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
1f7a0 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
1f7b0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
1f7c0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
1f7d0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
1f7e0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
1f7f0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
1f800 43 41 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c  CAPI3REF:  Enabl
1f810 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1f820 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
1f830 2a 0a 2a 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74  *.** So as not t
1f840 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
1f850 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
1f860 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1f870 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
1f880 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
1f890 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
1f8a0 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
1f8b0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
1f8c0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
1f8d0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
1f8e0 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
1f8f0 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
1f900 77 69 6e 67 0a 2a 2a 20 41 50 49 20 69 73 20 70  wing.** API is p
1f910 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
1f920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
1f930 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
1f940 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 0a  echanism on and.
1f950 2a 2a 20 6f 66 66 2e 20 20 49 74 20 69 73 20 6f  ** off.  It is o
1f960 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ff by default.  
1f970 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
1f980 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 20 74 68 69  ..**.** Call thi
1f990 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f  s routine with o
1f9a0 6e 6f 66 66 3d 3d 31 20 74 6f 20 74 75 72 6e 20  noff==1 to turn 
1f9b0 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
1f9c0 67 20 6f 6e 0a 2a 2a 20 61 6e 64 20 63 61 6c 6c  g on.** and call
1f9d0 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d   it with onoff==
1f9e0 30 20 74 6f 20 74 75 72 6e 20 69 74 20 62 61 63  0 to turn it bac
1f9f0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
1fa00 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
1fa10 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
1fa20 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
1fa30 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
1fa40 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 6b 65  * CAPI3REF: Make
1fa50 20 41 72 72 61 6e 67 65 6d 65 6e 74 73 20 54 6f   Arrangements To
1fa60 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
1fa70 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
1fa80 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 20  .**.** Register 
1fa90 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  an extension ent
1faa0 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73  ry point that is
1fab0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
1fac0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 65 76  nvoked.** whenev
1fad0 65 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  er a new databas
1fae0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1faf0 6f 70 65 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  opened using.** 
1fb00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1fb10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1fb20 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
1fb30 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
1fb40 0a 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e  .** This API can
1fb50 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70   be invoked at p
1fb60 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69  rogram startup i
1fb70 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73  n order to regis
1fb80 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
1fb90 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69  re statically li
1fba0 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20  nked extensions 
1fbb0 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61  that will be ava
1fbc0 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c  ilable.** to all
1fbd0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1fbe0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
1fbf0 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
1fc00 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
1fc10 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
1fc20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 6c 74 69  is routine multi
1fc30 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
1fc40 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e  h the same exten
1fc50 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73  sion is harmless
1fc60 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
1fc70 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
1fc80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
1fc90 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
1fca0 61 79 0a 2a 2a 20 74 68 61 74 20 69 73 20 6f 62  ay.** that is ob
1fcb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c  tained from mall
1fcc0 6f 63 28 29 2e 20 20 49 66 20 79 6f 75 20 72 75  oc().  If you ru
1fcd0 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 0a  n a memory leak.
1fce0 2a 2a 20 63 68 65 63 6b 65 72 20 6f 6e 20 79 6f  ** checker on yo
1fcf0 75 72 20 70 72 6f 67 72 61 6d 20 61 6e 64 20 69  ur program and i
1fd00 74 20 72 65 70 6f 72 74 73 20 61 20 6c 65 61 6b  t reports a leak
1fd10 20 62 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   because of this
1fd20 0a 2a 2a 20 61 72 72 61 79 2c 20 74 68 65 6e 20  .** array, then 
1fd30 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
1fd40 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
1fd50 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 0a 2a 2a  sion()] prior.**
1fd60 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74 6f 20   to shutdown to 
1fd70 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 2e  free the memory.
1fd80 0a 2a 2a 0a 2a 2a 20 41 75 74 6f 6d 61 74 69 63  .**.** Automatic
1fd90 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
1fda0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
1fdb0 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eads..**.** This
1fdc0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 78   interface is ex
1fdd0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1fde0 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
1fdf0 6e 67 65 20 6f 72 0a 2a 2a 20 72 65 6d 6f 76 61  nge or.** remova
1fe00 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  l in future rele
1fe10 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
1fe20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
1fe30 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
1fe40 69 64 20 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  id *xEntryPoint)
1fe50 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
1fe60 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
1fe70 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
1fe80 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 44 69 73 61  ading.**.** Disa
1fe90 62 6c 65 20 61 6c 6c 20 70 72 65 76 69 6f 75 73  ble all previous
1fea0 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75  ly registered au
1feb0 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
1fec0 6e 73 2e 20 20 54 68 69 73 0a 2a 2a 20 72 6f 75  ns.  This.** rou
1fed0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
1fee0 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
1fef0 69 6f 72 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  ior [sqlite3_aut
1ff00 6f 6d 61 74 69 63 5f 65 78 74 65 6e 73 69 6f 6e  omatic_extension
1ff10 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 2e 0a 2a 2a  ()].** calls..**
1ff20 0a 2a 2a 20 54 68 69 73 20 63 61 6c 6c 20 64 69  .** This call di
1ff30 73 61 62 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  sabled automatic
1ff40 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
1ff50 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a  ll threads..**.*
1ff60 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1ff70 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   is experimental
1ff80 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20   and is subject 
1ff90 74 6f 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  to change or.** 
1ffa0 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72  removal in futur
1ffb0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
1ffc0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  Lite..*/.void sq
1ffd0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
1ffe0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
1fff0 3b 0a 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58  ;.../*.****** EX
20000 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62  PERIMENTAL - sub
20010 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77  ject to change w
20020 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a  ithout notice **
20030 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a  ************.**.
20040 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
20050 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
20060 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
20070 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
20080 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
20090 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
200a0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
200b0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
200c0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
200d0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
200e0 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
200f0 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
20100 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
20110 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
20120 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
20130 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
20140 73 74 61 62 6c 69 7a 65 73 2c 20 77 65 20 77 69  stablizes, we wi
20150 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
20160 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
20170 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
20180 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
20190 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
201a0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
201b0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
201c0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
201d0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
201e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
201f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
20200 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
20210 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
20220 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
20230 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
20240 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
20250 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
20260 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
20270 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
20280 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
20290 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
202a0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 41 20  odule;../*.** A 
202b0 6d 6f 64 75 6c 65 20 69 73 20 61 20 63 6c 61 73  module is a clas
202c0 73 20 6f 66 20 76 69 72 74 75 61 6c 20 74 61 62  s of virtual tab
202d0 6c 65 73 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  les.  Each modul
202e0 65 20 69 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20  e is defined.** 
202f0 62 79 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  by an instance o
20300 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
20310 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69 73  structure.  This
20320 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
20330 73 74 73 0a 2a 2a 20 6d 6f 73 74 6c 79 20 6f 66  sts.** mostly of
20340 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   methods for the
20350 20 6d 6f 64 75 6c 65 2e 0a 2a 2f 0a 73 74 72 75   module..*/.stru
20360 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
20370 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  e {.  int iVersi
20380 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65  on;.  int (*xCre
20390 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ate)(sqlite3*, v
203a0 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
203b0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
203c0 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
203d0 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
203e0 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
203f0 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
20400 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
20410 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c   (*xConnect)(sql
20420 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
20430 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
20440 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
20450 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
20460 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
20470 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
20480 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
20490 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74  );.  int (*xBest
204a0 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76  Index)(sqlite3_v
204b0 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69  tab *pVTab, sqli
204c0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29  te3_index_info*)
204d0 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f  ;.  int (*xDisco
204e0 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76  nnect)(sqlite3_v
204f0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
20500 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73  nt (*xDestroy)(s
20510 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
20520 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70  ab);.  int (*xOp
20530 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  en)(sqlite3_vtab
20540 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
20550 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70  _vtab_cursor **p
20560 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20  pCursor);.  int 
20570 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
20580 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
20590 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72  .  int (*xFilter
205a0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
205b0 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e  ursor*, int idxN
205c0 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  um, const char *
205d0 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20  idxStr,.        
205e0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
205f0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
20600 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28  **argv);.  int (
20610 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f  *xNext)(sqlite3_
20620 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
20630 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c   int (*xEof)(sql
20640 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
20650 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c  *);.  int (*xCol
20660 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  umn)(sqlite3_vta
20670 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
20680 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
20690 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69  );.  int (*xRowi
206a0 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  d)(sqlite3_vtab_
206b0 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
206c0 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b  _int64 *pRowid);
206d0 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65  .  int (*xUpdate
206e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
206f0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76  , int, sqlite3_v
20700 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33  alue **, sqlite3
20710 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74  _int64 *);.  int
20720 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74   (*xBegin)(sqlit
20730 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
20740 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
20750 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
20760 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  Tab);.  int (*xC
20770 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76  ommit)(sqlite3_v
20780 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
20790 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28  nt (*xRollback)(
207a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
207b0 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Tab);.  int (*xF
207c0 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c  indFunction)(sql
207d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
207e0 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73  , int nArg, cons
207f0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20  t char *zName,. 
20800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20810 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78        void (**px
20820 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
20830 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
20840 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20  e3_value**),.   
20850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20860 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67      void **ppArg
20870 29 3b 0a 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  );..  int (*xRen
20880 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
20890 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
208a0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a  char *zNew);.};.
208b0 0a 2f 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ./*.** The sqlit
208c0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
208d0 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
208e0 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
208f0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
20900 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
20910 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
20920 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
20930 20 78 42 65 73 74 49 6e 64 65 78 0a 2a 2a 20 6d   xBestIndex.** m
20940 65 74 68 6f 64 20 6f 66 20 61 6e 20 73 71 6c 69  ethod of an sqli
20950 74 65 33 5f 6d 6f 64 75 6c 65 2e 20 20 54 68 65  te3_module.  The
20960 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a   fields under **
20970 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65  Inputs** are the
20980 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42  .** inputs to xB
20990 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65  estIndex and are
209a0 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65   read-only.  xBe
209b0 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20  stIndex inserts 
209c0 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  its.** results i
209d0 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74  nto the **Output
209e0 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a  s** fields..**.*
209f0 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  * The aConstrain
20a00 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64  t[] array record
20a10 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  s WHERE clause c
20a20 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68  onstraints of th
20a30 65 0a 2a 2a 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a  e.** form:.**.**
20a40 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20           column 
20a50 4f 50 20 65 78 70 72 0a 2a 2a 0a 2a 2a 20 57 68  OP expr.**.** Wh
20a60 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 3c 2c 20  ere OP is =, <, 
20a70 3c 3d 2c 20 3e 2c 20 6f 72 20 3e 3d 2e 20 20 54  <=, >, or >=.  T
20a80 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70  he particular op
20a90 65 72 61 74 6f 72 20 69 73 20 73 74 6f 72 65 64  erator is stored
20aa0 0a 2a 2a 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  .** in aConstrai
20ab0 6e 74 5b 5d 2e 6f 70 2e 20 20 54 68 65 20 69 6e  nt[].op.  The in
20ac0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
20ad0 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 0a  n is stored in .
20ae0 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ** aConstraint[]
20af0 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61 43 6f 6e 73  .iColumn.  aCons
20b00 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
20b10 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
20b20 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
20b30 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
20b40 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
20b50 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
20b60 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
20b70 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
20b80 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 0a 2a 2a  if it cannot..**
20b90 0a 2a 2a 20 54 68 65 20 6f 70 74 69 6d 69 7a 65  .** The optimize
20ba0 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
20bb0 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
20bc0 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
20bd0 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
20be0 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
20bf0 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
20c00 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
20c10 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
20c20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
20c30 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
20c40 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
20c50 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
20c60 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 54  s possible..** T
20c70 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
20c80 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f   array only repo
20c90 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65  rts WHERE clause
20ca0 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 63 6f   terms in the co
20cb0 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d 20 74 68  rrect.** form th
20cc0 61 74 20 72 65 66 65 72 20 74 6f 20 74 68 65 20  at refer to the 
20cd0 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
20ce0 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
20cf0 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ueried..**.** In
20d00 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
20d10 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
20d20 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
20d30 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
20d40 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72  Each term of aOr
20d50 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20  derBy records a 
20d60 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52  column of the OR
20d70 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a  DER BY clause..*
20d80 2a 0a 2a 2a 20 54 68 65 20 78 42 65 73 74 49 6e  *.** The xBestIn
20d90 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  dex method must 
20da0 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74  fill aConstraint
20db0 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66  Usage[] with inf
20dc0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
20dd0 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72  t what parameter
20de0 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69  s to pass to xFi
20df0 6c 74 65 72 2e 20 20 49 66 20 61 72 67 76 49 6e  lter.  If argvIn
20e00 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
20e10 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
20e20 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
20e30 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
20e40 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
20e50 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
20e60 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
20e70 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
20e80 20 20 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74    If aConstraint
20e90 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
20ea0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
20eb0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
20ec0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
20ed0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
20ee0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
20ef0 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
20f00 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
20f10 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
20f20 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
20f30 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
20f40 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
20f50 65 64 20 69 6e 74 6f 20 78 46 69 6c 74 65 72 2e  ed into xFilter.
20f60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
20f70 28 29 20 69 73 20 75 73 65 64 20 74 6f 20 66 72  () is used to fr
20f80 65 65 20 69 64 78 50 74 72 20 69 66 20 6e 65 65  ee idxPtr if nee
20f90 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
20fa0 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   true..**.** The
20fb0 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64   orderByConsumed
20fc0 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70   means that outp
20fd0 75 74 20 66 72 6f 6d 20 78 46 69 6c 74 65 72 20  ut from xFilter 
20fe0 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
20ff0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
21000 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
21010 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
21020 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
21030 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
21040 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
21050 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 73 74  d..**.** The est
21060 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
21070 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
21080 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
21090 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
210a0 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
210b0 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
210c0 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
210d0 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
210e0 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
210f0 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
21100 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
21110 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
21120 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
21130 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
21140 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
21150 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
21160 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
21170 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
21180 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
21190 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
211a0 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
211b0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
211c0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
211d0 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
211e0 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
211f0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
21200 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
21210 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
21220 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
21230 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
21240 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
21250 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
21260 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
21270 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
21280 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
21290 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
212a0 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
212b0 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
212c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
212d0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
212e0 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
212f0 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
21300 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
21310 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
21320 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
21330 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
21340 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
21350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21360 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
21370 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
21380 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
21390 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
213a0 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
213b0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
213c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
213d0 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
213e0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
213f0 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
21400 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
21410 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
21420 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
21430 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
21440 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
21450 63 6c 61 75 73 65 20 2a 2f 0a 0a 20 20 2f 2a 20  clause */..  /* 
21460 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
21470 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
21480 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
21490 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
214a0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
214b0 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
214c0 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
214d0 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
214e0 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
214f0 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
21500 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
21510 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
21520 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
21530 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
21540 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
21550 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
21560 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
21570 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
21580 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
21590 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
215a0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
215b0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
215c0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
215d0 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
215e0 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
215f0 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
21600 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
21610 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
21620 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
21630 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
21640 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
21650 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
21660 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
21670 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
21680 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
21690 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
216a0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
216b0 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
216c0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
216d0 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
216e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
216f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
21700 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
21710 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
21720 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
21730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
21740 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
21750 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
21760 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
21770 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
21780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
21790 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
217a0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
217b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
217c0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
217d0 20 61 20 6e 65 77 20 6d 6f 64 75 6c 65 20 6e 61   a new module na
217e0 6d 65 20 77 69 74 68 20 61 6e 20 53 51 4c 69 74  me with an SQLit
217f0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
21800 20 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d    Module names m
21810 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
21820 64 20 62 65 66 6f 72 65 20 63 72 65 61 74 69 6e  d before creatin
21830 67 20 6e 65 77 0a 2a 2a 20 76 69 72 74 75 61 6c  g new.** virtual
21840 20 74 61 62 6c 65 73 20 6f 6e 20 74 68 65 20 6d   tables on the m
21850 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66 6f 72 65  odule, or before
21860 20 75 73 69 6e 67 20 70 72 65 65 78 69 73 74 69   using preexisti
21870 6e 67 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  ng virtual.** ta
21880 62 6c 65 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  bles of the modu
21890 6c 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  le..*/.int sqlit
218a0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
218b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
218c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
218d0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
218e0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
218f0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
21900 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
21910 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
21920 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
21930 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
21940 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20  ite3_module *,  
21950 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
21960 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
21970 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20   void *         
21980 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
21990 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
219a0 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
219b0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69  */.);../*.** Thi
219c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 64 65  s routine is ide
219d0 6e 74 69 63 61 6c 20 74 6f 20 74 68 65 20 73 71  ntical to the sq
219e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
219f0 75 6c 65 28 29 20 6d 65 74 68 6f 64 20 61 62 6f  ule() method abo
21a00 76 65 2c 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ve,.** except th
21a10 61 74 20 69 74 20 61 6c 6c 6f 77 73 20 61 20 64  at it allows a d
21a20 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
21a30 6f 6e 20 74 6f 20 62 65 20 73 70 65 63 69 66 69  on to be specifi
21a40 65 64 2e 20 49 74 20 69 73 0a 2a 2a 20 65 76 65  ed. It is.** eve
21a50 6e 20 6d 6f 72 65 20 65 78 70 65 72 69 6d 65 6e  n more experimen
21a60 74 61 6c 20 74 68 61 6e 20 74 68 65 20 72 65 73  tal than the res
21a70 74 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  t of the virtual
21a80 20 74 61 62 6c 65 73 20 41 50 49 2e 0a 2a 2f 0a   tables API..*/.
21a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
21aa0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
21ab0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
21ac0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
21ad0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
21ae0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
21af0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
21b00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
21b10 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
21b20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
21b30 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
21b40 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20 20 20 2f 2a  _module *,    /*
21b50 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
21b60 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
21b70 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
21b80 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
21b90 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
21ba0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
21bb0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
21bc0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
21bd0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
21be0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
21bf0 0a 2f 2a 0a 2a 2a 20 45 76 65 72 79 20 6d 6f 64  ./*.** Every mod
21c00 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
21c10 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
21c20 73 73 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ss of the follow
21c30 69 6e 67 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ing structure.**
21c40 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
21c50 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
21c60 63 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ce of the module
21c70 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
21c80 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c   will.** be tail
21c90 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
21ca0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
21cb0 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
21cc0 6e 74 61 74 69 6f 6e 2e 20 20 20 54 68 65 0a 2a  ntation.   The.*
21cd0 2a 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69  * purpose of thi
21ce0 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20  s superclass is 
21cf0 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69  to define certai
21d00 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72  n fields that ar
21d10 65 20 63 6f 6d 6d 6f 6e 0a 2a 2a 20 74 6f 20 61  e common.** to a
21d20 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ll module implem
21d30 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  entations..**.**
21d40 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
21d50 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
21d60 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21d70 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
21d80 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
21d90 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
21da0 6d 70 72 69 6e 74 66 28 29 20 74 6f 20 7a 45 72  mprintf() to zEr
21db0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
21dc0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
21dd0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
21de0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
21df0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
21e00 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
21e10 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
21e20 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
21e30 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
21e40 20 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   After the error
21e50 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
21e60 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
21e70 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
21e80 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
21e90 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
21ea0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
21eb0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
21ec0 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
21ed0 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
21ee0 20 7a 65 72 6f 65 64 2e 20 20 4e 6f 74 65 0a 2a   zeroed.  Note.*
21ef0 2a 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 6d  * that sqlite3_m
21f00 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
21f10 69 74 65 33 5f 66 72 65 65 28 29 20 61 72 65 20  ite3_free() are 
21f20 75 73 65 64 20 6f 6e 20 74 68 65 20 7a 45 72 72  used on the zErr
21f30 4d 73 67 20 66 69 65 6c 64 0a 2a 2a 20 73 69 6e  Msg field.** sin
21f40 63 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ce virtual table
21f50 73 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 69  s are commonly i
21f60 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 6c 6f  mplemented in lo
21f70 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
21f80 73 20 77 68 69 63 68 0a 2a 2a 20 64 6f 20 6e 6f  s which.** do no
21f90 74 20 68 61 76 65 20 61 63 63 65 73 73 20 74 6f  t have access to
21fa0 20 73 71 6c 69 74 65 33 4d 50 72 69 6e 74 66 28   sqlite3MPrintf(
21fb0 29 20 6f 72 20 73 71 6c 69 74 65 33 46 72 65 65  ) or sqlite3Free
21fc0 28 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ()..*/.struct sq
21fd0 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
21fe0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
21ff0 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
22000 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
22010 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
22020 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
22030 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
22040 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
22050 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2a 2f 0a 20   internally */. 
22060 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
22070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22080 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
22090 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
220a0 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
220b0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
220c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
220d0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
220e0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
220f0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 20 45 76  lds */.};../* Ev
22100 65 72 79 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ery module imple
22110 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
22120 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
22130 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
22140 74 75 72 65 0a 2a 2a 20 74 6f 20 64 65 73 63 72  ture.** to descr
22150 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
22160 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 20   point into the 
22170 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
22180 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
22190 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
221a0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
221b0 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
221c0 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
221d0 2a 2a 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  ** xOpen method 
221e0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20  of the module.  
221f0 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c  Each module impl
22200 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
22210 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f  define.** the co
22220 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f  ntent of a curso
22230 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73  r structure to s
22240 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64  uit its own need
22250 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75  s..**.** This su
22260 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20  perclass exists 
22270 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69  in order to defi
22280 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65  ne fields of the
22290 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20   cursor that.** 
222a0 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  are common to al
222b0 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  l implementation
222c0 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  s..*/.struct sql
222d0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
222e0 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61   {.  sqlite3_vta
222f0 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f  b *pVtab;      /
22300 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
22310 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a  of this cursor *
22320 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
22330 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
22340 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
22350 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
22360 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
22370 0a 2f 2a 0a 2a 2a 20 54 68 65 20 78 43 72 65 61  ./*.** The xCrea
22380 74 65 20 61 6e 64 20 78 43 6f 6e 6e 65 63 74 20  te and xConnect 
22390 6d 65 74 68 6f 64 73 20 6f 66 20 61 20 6d 6f 64  methods of a mod
223a0 75 6c 65 20 75 73 65 20 74 68 65 20 66 6f 6c 6c  ule use the foll
223b0 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 74 6f 20  owing API.** to 
223c0 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
223d0 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
223e0 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
223f0 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
22400 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
22410 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
22420 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
22430 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
22440 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
22450 20 63 68 61 72 20 2a 7a 43 72 65 61 74 65 54 61   char *zCreateTa
22460 62 6c 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 56 69 72  ble);../*.** Vir
22470 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
22480 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
22490 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
224a0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
224b0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 78 46  .** using the xF
224c0 69 6e 64 46 75 6e 63 74 69 6f 6e 20 6d 65 74 68  indFunction meth
224d0 6f 64 2e 20 20 42 75 74 20 67 6c 6f 62 61 6c 20  od.  But global 
224e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73  versions of thos
224f0 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d  e functions.** m
22500 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64  ust exist in ord
22510 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61  er to be overloa
22520 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ded..**.** This 
22530 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
22540 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
22550 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
22560 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
22570 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
22580 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
22590 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
225a0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
225b0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
225c0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
225d0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
225e0 6e 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  n is created.  T
225f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
22600 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
22610 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
22620 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
22630 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
22640 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
22650 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
22660 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
22670 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
22680 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
22690 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
226a0 61 63 65 2d 68 6f 6c 64 65 72 20 66 75 6e 63 74  ace-holder funct
226b0 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20  ion that can be 
226c0 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79  overloaded.** by
226d0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 2e   virtual tables.
226e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
226f0 73 68 6f 75 6c 64 20 62 65 20 63 6f 6e 73 69 64  should be consid
22700 65 72 65 64 20 70 61 72 74 20 6f 66 20 74 68 65  ered part of the
22710 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
22720 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 77 68 69  nterface,.** whi
22730 63 68 20 69 73 20 65 78 70 65 72 69 6d 65 6e 74  ch is experiment
22740 61 6c 20 61 6e 64 20 73 75 62 6a 65 63 74 20 74  al and subject t
22750 6f 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  o change..*/.int
22760 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
22770 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
22780 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
22790 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
227a0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
227b0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
227c0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
227d0 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
227e0 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
227f0 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
22800 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
22810 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
22820 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
22830 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
22840 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
22850 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
22860 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
22870 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
22880 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
22890 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
228a0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
228b0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
228c0 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
228d0 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
228e0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
228f0 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
22900 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
22910 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
22920 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
22930 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
22940 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
22950 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  omment..**.*****
22960 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d  * EXPERIMENTAL -
22970 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
22980 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63  ge without notic
22990 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e **************
229a0 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
229b0 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
229c0 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
229d0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
229e0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
229f0 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72   opaque structur
22a00 65 20 69 73 20 75 73 65 64 20 74 6f 20 0a 2a 2a  e is used to .**
22a10 20 72 65 70 72 65 73 65 6e 74 20 61 6e 20 62 6c   represent an bl
22a20 6f 62 2d 68 61 6e 64 6c 65 2e 20 20 41 20 62 6c  ob-handle.  A bl
22a30 6f 62 2d 68 61 6e 64 6c 65 20 69 73 20 63 72 65  ob-handle is cre
22a40 61 74 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  ated by.** [sqli
22a50 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
22a60 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62   and destroyed b
22a70 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
22a80 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  close()]..** The
22a90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
22aa0 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
22ab0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
22ac0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
22ad0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
22ae0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
22af0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
22b00 66 20 74 68 65 20 62 6c 6f 62 2e 0a 2a 2a 20 54  f the blob..** T
22b10 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
22b20 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
22b30 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
22b40 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 62  size of the.** b
22b50 6c 6f 62 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  lob in bytes..*/
22b60 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
22b70 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
22b80 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
22b90 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
22ba0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
22bb0 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
22bc0 2a 20 4f 70 65 6e 20 61 20 68 61 6e 64 6c 65 20  * Open a handle 
22bd0 74 6f 20 74 68 65 20 62 6c 6f 62 20 6c 6f 63 61  to the blob loca
22be0 74 65 64 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c  ted in row iRow,
22bf0 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
22c00 2c 20 0a 2a 2a 20 74 61 62 6c 65 20 7a 54 61 62  , .** table zTab
22c10 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a  le in database z
22c20 44 62 2e 20 69 2e 65 2e 20 74 68 65 20 73 61 6d  Db. i.e. the sam
22c30 65 20 62 6c 6f 62 20 74 68 61 74 20 77 6f 75 6c  e blob that woul
22c40 64 0a 2a 2a 20 62 65 20 73 65 6c 65 63 74 65 64  d.** be selected
22c50 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
22c60 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
22c70 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
22c80 7a 54 61 62 6c 65 20 57 48 45 52 45 20 72 6f 77  zTable WHERE row
22c90 69 64 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  id = iRow;.** </
22ca0 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  pre>.**.** If th
22cb0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
22cc0 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  r is non-zero, t
22cd0 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e 65  he blob is opene
22ce0 64 20 66 6f 72 20 0a 2a 2a 20 72 65 61 64 20 61  d for .** read a
22cf0 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
22d00 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20   If it is zero, 
22d10 74 68 65 20 62 6c 6f 62 20 69 73 20 6f 70 65 6e  the blob is open
22d20 65 64 20 66 6f 72 20 72 65 61 64 20 0a 2a 2a 20  ed for read .** 
22d30 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  access..**.** On
22d40 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
22d50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
22d60 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 0a 2a  d and the new .*
22d70 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
22d80 7c 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 20 69  | blob handle] i
22d90 73 20 77 72 69 74 74 65 6e 20 74 6f 20 2a 70 70  s written to *pp
22da0 42 6c 6f 62 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  Blob..** Otherwi
22db0 73 65 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65  se an error code
22dc0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
22dd0 20 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 77   .** any value w
22de0 72 69 74 74 65 6e 20 74 6f 20 2a 70 70 42 6c 6f  ritten to *ppBlo
22df0 62 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  b should not be 
22e00 75 73 65 64 20 62 79 20 74 68 65 20 63 61 6c 6c  used by the call
22e10 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  er..** This func
22e20 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 64 61  tion sets the da
22e30 74 61 62 61 73 65 2d 68 61 6e 64 6c 65 20 65 72  tabase-handle er
22e40 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
22e50 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
22e60 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
22e70 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
22e80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
22e90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
22ea0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
22eb0 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
22ec0 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
22ed0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
22ee0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
22ef0 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
22f00 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
22f10 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
22f20 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
22f30 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
22f40 50 49 33 52 45 46 3a 20 20 43 6c 6f 73 65 20 41  PI3REF:  Close A
22f50 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a   BLOB Handle.**.
22f60 2a 2a 20 43 6c 6f 73 65 20 61 6e 20 6f 70 65 6e  ** Close an open
22f70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c   [sqlite3_blob |
22f80 20 62 6c 6f 62 20 68 61 6e 64 6c 65 5d 2e 0a 2a   blob handle]..*
22f90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
22fa0 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
22fb0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
22fc0 20 43 41 50 49 33 52 45 46 3a 20 20 52 65 74 75   CAPI3REF:  Retu
22fd0 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
22fe0 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
22ff0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
23000 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68  e in bytes of th
23010 65 20 62 6c 6f 62 20 61 63 63 65 73 73 69 62 6c  e blob accessibl
23020 65 20 76 69 61 20 74 68 65 20 6f 70 65 6e 20 0a  e via the open .
23030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
23040 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20   | blob-handle] 
23050 70 61 73 73 65 64 20 61 73 20 61 6e 20 61 72 67  passed as an arg
23060 75 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ument..*/.int sq
23070 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
23080 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
23090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
230a0 46 3a 20 20 52 65 61 64 20 44 61 74 61 20 46 72  F:  Read Data Fr
230b0 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  om A BLOB Increm
230c0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54 68  entally.**.** Th
230d0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
230e0 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
230f0 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 0a 2a   from an open .*
23100 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  * [sqlite3_blob 
23110 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d 20 69  | blob-handle] i
23120 6e 74 6f 20 61 20 63 61 6c 6c 65 72 20 73 75 70  nto a caller sup
23130 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
23140 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
23150 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
23160 20 62 75 66 66 65 72 0a 2a 2a 20 7a 20 66 72 6f   buffer.** z fro
23170 6d 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f 62 2c  m the open blob,
23180 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
23190 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
231a0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53  ** On success, S
231b0 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
231c0 72 6e 65 64 2e 20 4f 74 68 65 72 77 69 73 65 2c  rned. Otherwise,
231d0 20 61 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   an .** [SQLITE_
231e0 45 52 52 4f 52 20 7c 20 53 51 4c 69 74 65 20 65  ERROR | SQLite e
231f0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
23200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
23210 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
23220 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
23230 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 0a 69 6e   returned..*/.in
23240 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
23250 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
23260 20 2a 2c 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74   *, void *z, int
23270 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
23280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23290 46 3a 20 20 57 72 69 74 65 20 44 61 74 61 20 49  F:  Write Data I
232a0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  nto A BLOB Incre
232b0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 54  mentally.**.** T
232c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
232d0 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
232e0 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
232f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
23300 62 20 7c 20 62 6c 6f 62 2d 68 61 6e 64 6c 65 5d  b | blob-handle]
23310 20 66 72 6f 6d 20 61 20 75 73 65 72 20 73 75 70   from a user sup
23320 70 6c 69 65 64 20 62 75 66 66 65 72 2e 0a 2a 2a  plied buffer..**
23330 20 6e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   n bytes of data
23340 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
23350 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 70   the buffer.** p
23360 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 7a 20 69  ointed to by z i
23370 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 62 6c 6f  nto the open blo
23380 62 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  b, starting at o
23390 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
233a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
233b0 69 74 65 33 5f 62 6c 6f 62 20 7c 20 62 6c 6f 62  ite3_blob | blob
233c0 2d 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20  -handle] passed 
233d0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
233e0 75 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 6e 6f 74  ument.** was not
233f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 77 72 69 74   opened for writ
23400 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
23410 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
23420 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
23430 5d 0a 2a 2a 2a 20 77 61 73 20 7a 65 72 6f 29 2c  ].*** was zero),
23440 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
23450 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
23460 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
23470 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
23480 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
23490 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
234a0 65 20 62 6c 6f 62 2c 20 69 74 20 69 73 0a 2a 2a  e blob, it is.**
234b0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
234c0 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
234d0 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 75 73 69  ze of a blob usi
234e0 6e 67 20 74 68 69 73 20 41 50 49 2e 20 49 66 0a  ng this API. If.
234f0 2a 2a 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  ** offset iOffse
23500 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6e  t is less than n
23510 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
23520 65 6e 64 20 6f 66 20 74 68 65 20 62 6c 6f 62 2c  end of the blob,
23530 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
23540 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
23550 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
23560 72 69 74 74 65 6e 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ritten..**.** On
23570 20 73 75 63 63 65 73 73 2c 20 53 51 4c 49 54 45   success, SQLITE
23580 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
23590 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 0a   Otherwise, an .
235a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
235b0 20 7c 20 53 51 4c 69 74 65 20 65 72 72 6f 72 20   | SQLite error 
235c0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
235d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
235e0 44 20 7c 20 65 78 74 65 6e 64 65 64 20 65 72 72  D | extended err
235f0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
23600 72 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rned..*/.int sql
23610 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
23620 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
23630 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
23640 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
23650 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23660 52 45 46 3a 20 20 56 69 72 74 75 61 6c 20 46 69  REF:  Virtual Fi
23670 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
23680 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
23690 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
236a0 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
236b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
236c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
236d0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
236e0 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
236f0 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
23700 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 62 75 69  ystem.  Most bui
23710 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a  lds come with a.
23720 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c  ** single defaul
23730 74 20 56 46 53 20 74 68 61 74 20 69 73 20 61 70  t VFS that is ap
23740 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
23750 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e  e host computer.
23760 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61  .** New VFSes ca
23770 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
23780 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56 46 53  and existing VFS
23790 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69  es can be unregi
237a0 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66  stered..** The f
237b0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
237c0 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
237d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
237e0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69  te3_vfs_find() i
237f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23800 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
23810 56 46 53 20 67 69 76 65 6e 20 69 74 73 0a 2a 2a  VFS given its.**
23820 20 6e 61 6d 65 2e 20 20 4e 61 6d 65 73 20 61 72   name.  Names ar
23830 65 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65  e case sensitive
23840 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
23850 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 0a  o match, a NULL.
23860 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  ** pointer is re
23870 74 75 72 6e 65 64 2e 20 20 49 66 20 7a 56 66 73  turned.  If zVfs
23880 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65  Name is NULL the
23890 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a 2a  n the default .*
238a0 2a 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  * VFS is returne
238b0 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53  d..**.** New VFS
238c0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
238d0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
238e0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20 20  fs_register().  
238f0 45 61 63 68 0a 2a 2a 20 6e 65 77 20 56 46 53 20  Each.** new VFS 
23900 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
23910 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
23920 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
23930 73 65 74 2e 0a 2a 2a 20 54 68 65 20 73 61 6d 65  set..** The same
23940 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67 69   VFS can be regi
23950 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
23960 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69 6e  times without in
23970 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65  jury..** To make
23980 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53   an existing VFS
23990 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c   into the defaul
239a0 74 20 56 46 53 2c 20 72 65 67 69 73 74 65 72 20  t VFS, register 
239b0 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68  it again.** with
239c0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
239d0 61 67 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20  ag set.  If two 
239e0 64 69 66 66 65 72 65 6e 74 20 56 46 53 65 73 20  different VFSes 
239f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65  with the.** same
23a00 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69 73 74   name are regist
23a10 65 72 65 64 2c 20 74 68 65 20 62 65 68 61 76 69  ered, the behavi
23a20 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
23a30 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73    If a.** VFS is
23a40 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
23a50 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20   a name that is 
23a60 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
23a70 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e   string,.** then
23a80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23a90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 0a   undefined..** .
23aa0 2a 2a 20 55 6e 72 65 67 69 73 74 65 72 20 61 20  ** Unregister a 
23ab0 56 46 53 20 77 69 74 68 20 74 68 65 20 73 71 6c  VFS with the sql
23ac0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
23ad0 74 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  ter() interface.
23ae0 0a 2a 2a 20 49 66 20 74 68 65 20 64 65 66 61 75  .** If the defau
23af0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
23b00 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
23b10 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
23b20 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
23b30 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
23b40 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
23b50 61 72 62 69 74 72 61 72 79 2e 0a 2a 2f 0a 73 71  arbitrary..*/.sq
23b60 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74  lite3_vfs *sqlit
23b70 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73  e3_vfs_find(cons
23b80 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65  t char *zVfsName
23b90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
23ba0 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69  fs_register(sqli
23bb0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61  te3_vfs*, int ma
23bc0 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c  keDflt);.int sql
23bd0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
23be0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
23bf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23c00 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a  EF: Mutexes.**.*
23c10 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
23c20 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  e uses these rou
23c30 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64  tines for thread
23c40 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74  .** synchronizat
23c50 69 6f 6e 2e 20 20 54 68 6f 75 67 68 20 74 68 65  ion.  Though the
23c60 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
23c70 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
23c80 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
23c90 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
23ca0 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
23cb0 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
23cc0 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
23cd0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
23ce0 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
23cf0 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
23d00 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
23d10 65 6e 74 61 74 69 6f 6e 73 20 0a 2a 2a 20 6f 66  entations .** of
23d20 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
23d30 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
23d40 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
23d50 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
23d60 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
23d70 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
23d80 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
23d90 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
23da0 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
23db0 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
23dc0 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
23dd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
23de0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
23df0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
23e00 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
23e10 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
23e20 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
23e30 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
23e40 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
23e50 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
23e60 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
23e70 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
23e80 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 0a 2a 2a   of routines .**
23e90 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65   that does no re
23ea0 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69  al locking and i
23eb0 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
23ec0 72 20 75 73 65 20 69 6e 20 0a 2a 2a 20 61 20 73  r use in .** a s
23ed0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
23ee0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
23ef0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53   SQLITE_MUTEX_OS
23f00 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  2,.** SQLITE_MUT
23f10 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20  EX_PTHREAD, and 
23f20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
23f30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
23f40 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69  .** are appropri
23f50 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 6f  ate for use on o
23f60 73 2f 32 2c 20 75 6e 69 78 2c 20 61 6e 64 20 77  s/2, unix, and w
23f70 69 6e 64 6f 77 73 2e 0a 2a 2a 20 0a 2a 2a 20 49  indows..** .** I
23f80 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
23f90 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
23fa0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
23fb0 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
23fc0 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
23fd0 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
23fe0 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
23ff0 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
24000 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
24010 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
24020 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
24030 20 54 68 65 0a 2a 2a 20 6d 75 74 65 78 20 69 6e   The.** mutex in
24040 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
24050 20 64 65 66 69 6e 65 64 20 68 65 72 65 20 62 65   defined here be
24060 63 6f 6d 65 20 65 78 74 65 72 6e 61 6c 0a 2a 2a  come external.**
24070 20 72 65 66 65 72 65 6e 63 65 73 20 69 6e 20 74   references in t
24080 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
24090 79 20 66 6f 72 20 77 68 69 63 68 20 69 6d 70 6c  y for which impl
240a0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6d  ementations.** m
240b0 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20  ust be provided 
240c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
240d0 6f 6e 2e 20 20 54 68 69 73 20 66 61 63 69 6c 69  on.  This facili
240e0 74 79 20 61 6c 6c 6f 77 73 20 61 6e 0a 2a 2a 20  ty allows an.** 
240f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74  application that
24100 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53   links against S
24110 51 4c 69 74 65 20 74 6f 20 70 72 6f 76 69 64 65  QLite to provide
24120 20 69 74 73 20 6f 77 6e 20 6d 75 74 65 78 0a 2a   its own mutex.*
24130 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
24140 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20   without having 
24150 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  to modify the SQ
24160 4c 69 74 65 20 63 6f 72 65 2e 0a 2a 2a 0a 2a 2a  Lite core..**.**
24170 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
24180 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
24190 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
241a0 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
241b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
241c0 72 20 74 6f 20 69 74 2e 20 20 49 66 20 69 74 20  r to it.  If it 
241d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20  returns NULL.** 
241e0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20  that means that 
241f0 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f  a mutex could no
24200 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20  t be allocated. 
24210 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
24220 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b  unwind its stack
24230 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65   and return an e
24240 72 72 6f 72 2e 20 20 54 68 65 20 61 72 67 75 6d  rror.  The argum
24250 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
24260 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
24270 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
24280 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
24290 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
242a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
242b0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
242c0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
242d0 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
242e0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
242f0 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
24300 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
24310 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
24320 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
24330 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
24340 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
24350 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
24360 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
24370 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
24380 52 55 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  RU.** </ul>.**.*
24390 2a 20 54 68 65 20 66 69 72 73 74 20 74 77 6f 20  * The first two 
243a0 63 6f 6e 73 74 61 6e 74 73 20 63 61 75 73 65 20  constants cause 
243b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
243c0 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65 0a  loc() to create.
243d0 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e 20  ** a new mutex. 
243e0 20 54 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69   The new mutex i
243f0 73 20 72 65 63 75 72 73 69 76 65 20 77 68 65 6e  s recursive when
24400 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
24410 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73  CURSIVE.** is us
24420 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73  ed but not neces
24430 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53  sarily so when S
24440 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
24450 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65   is used..** The
24460 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
24470 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
24480 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69  eed to make a di
24490 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
244a0 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  ween SQLITE_MUTE
244b0 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e 64 20  X_RECURSIVE and 
244c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
244d0 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20  T if it does.** 
244e0 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20 42 75  not want to.  Bu
244f0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e  t SQLite will on
24500 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
24510 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
24520 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
24530 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
24540 6e 65 2e 20 20 49 66 20 61 20 66 61 73 74 65 72  ne.  If a faster
24550 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
24560 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
24570 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
24580 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
24590 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
245a0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
245b0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
245c0 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
245d0 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
245e0 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
245f0 2a 2a 20 54 68 65 20 6f 74 68 65 72 20 61 6c 6c  ** The other all
24600 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  owed parameters 
24610 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
24620 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20 72 65  _alloc() each re
24630 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
24640 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
24650 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
24660 20 20 46 6f 75 72 20 73 74 61 74 69 63 20 6d 75    Four static mu
24670 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  texes are.** use
24680 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
24690 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
246a0 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  te.  Future vers
246b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
246c0 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69  * may add additi
246d0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65  onal static mute
246e0 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74  xes.  Static mut
246f0 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74  exes are for int
24700 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
24710 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70  SQLite only.  Ap
24720 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
24730 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78  use SQLite mutex
24740 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65  es should.** use
24750 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69   only the dynami
24760 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e  c mutexes return
24770 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54  ed by SQLITE_MUT
24780 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51  EX_FAST or.** SQ
24790 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
247a0 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  SIVE..**.** Note
247b0 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
247c0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
247d0 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
247e0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
247f0 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
24800 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
24810 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
24820 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
24830 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
24840 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
24850 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 42 75   every call.  Bu
24860 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
24870 20 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73   .** mutex types
24880 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
24890 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
248a0 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
248b0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
248c0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
248d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
248e0 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
248f0 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
24900 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
24910 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
24920 63 20 6d 75 74 65 78 2e 20 20 53 51 4c 69 74 65  c mutex.  SQLite
24930 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
24940 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
24950 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
24960 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
24970 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
24980 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
24990 74 20 62 65 20 69 6e 20 0a 2a 2a 20 75 73 65 20  t be in .** use 
249a0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
249b0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65  allocated.  Atte
249c0 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
249d0 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
249e0 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
249f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
24a00 76 69 6f 72 2e 20 20 53 51 4c 69 74 65 20 6e 65  vior.  SQLite ne
24a10 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
24a20 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
24a30 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  x..**.** The sql
24a40 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
24a50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
24a60 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
24a70 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
24a80 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
24a90 20 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72    If another thr
24aa0 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
24ab0 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
24ac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
24ad0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
24ae0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
24af0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
24b00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
24b10 54 45 5f 42 55 53 59 2e 20 20 54 68 65 20 73 71  TE_BUSY.  The sq
24b20 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
24b30 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24b40 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 0a 2a 2a  rns SQLITE_OK.**
24b50 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
24b60 20 65 6e 74 72 79 2e 20 20 4d 75 74 65 78 65 73   entry.  Mutexes
24b70 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 53   created using S
24b80 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
24b90 52 53 49 56 45 20 63 61 6e 0a 2a 2a 20 62 65 20  RSIVE can.** be 
24ba0 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  entered multiple
24bb0 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73 61   times by the sa
24bc0 6d 65 20 74 68 72 65 61 64 2e 20 20 49 6e 20 73  me thread.  In s
24bd0 75 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a  uch cases the,.*
24be0 2a 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20  * mutex must be 
24bf0 65 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20  exited an equal 
24c00 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
24c10 62 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74  before another t
24c20 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74  hread.** can ent
24c30 65 72 2e 20 20 49 66 20 74 68 65 20 73 61 6d 65  er.  If the same
24c40 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
24c50 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
24c60 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 0a 2a   kind of mutex.*
24c70 2a 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  * more than once
24c80 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
24c90 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 20 53  s undefined.   S
24ca0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
24cb0 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
24cc0 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
24cd0 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
24ce0 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  xes..**.** Some 
24cf0 73 79 73 74 65 6d 73 20 28 65 78 3a 20 77 69 6e  systems (ex: win
24d00 64 6f 77 73 39 35 29 20 64 6f 20 6e 6f 74 20 74  dows95) do not t
24d10 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 6d 70  he operation imp
24d20 6c 65 6d 65 6e 74 65 64 20 62 79 0a 2a 2a 20 73  lemented by.** s
24d30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
24d40 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79  ().  On those sy
24d50 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d  stems, sqlite3_m
24d60 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 0a  utex_try() will.
24d70 2a 2a 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ** always return
24d80 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54   SQLITE_BUSY.  T
24d90 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
24da0 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a  nly ever uses.**
24db0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
24dc0 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d  ry() as an optim
24dd0 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20  ization so this 
24de0 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65  is acceptable be
24df0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
24e00 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
24e10 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65 20  leave() routine 
24e20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74 68  exits a mutex th
24e30 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  at was.** previo
24e40 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  usly entered by 
24e50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
24e60 20 20 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a    The behavior.*
24e70 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69  * is undefined i
24e80 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e  f the mutex is n
24e90 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ot currently ent
24ea0 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63  ered by the.** c
24eb0 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72  alling thread or
24ec0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24ed0 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51  y allocated.  SQ
24ee0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
24ef0 65 72 20 64 6f 20 65 69 74 68 65 72 2e 0a 2a 2a  er do either..**
24f00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
24f10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
24f20 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
24f30 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
24f40 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  )]..*/.sqlite3_m
24f50 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75  utex *sqlite3_mu
24f60 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  tex_alloc(int);.
24f70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74  void sqlite3_mut
24f80 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f  ex_free(sqlite3_
24f90 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
24fa0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
24fb0 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  r(sqlite3_mutex*
24fc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
24fd0 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33  utex_try(sqlite3
24fe0 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
24ff0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
25000 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ve(sqlite3_mutex
25010 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25020 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
25030 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
25040 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25050 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
25060 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
25070 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
25080 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
25090 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
250a0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
250b0 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 53 51 4c  ements.  The SQL
250c0 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
250d0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
250e0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
250f0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
25100 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
25110 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
25120 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
25130 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
25140 20 54 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a   The core only.*
25150 2a 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65  * provides imple
25160 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74  mentations for t
25170 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68  hese routines wh
25180 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
25190 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51  d.** with the SQ
251a0 4c 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e  LITE_DEBUG flag.
251b0 20 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78    External mutex
251c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
251d0 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71  .** are only req
251e0 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
251f0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
25200 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  if SQLITE_DEBUG 
25210 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e  is.** defined an
25220 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e  d if NDEBUG is n
25230 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ot defined..**.*
25240 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25250 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
25260 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78  rue if the mutex
25270 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65   in their argume
25280 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72  nt.** is held or
25290 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65   not held, respe
252a0 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20  ctively, by the 
252b0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a  calling thread..
252c0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  **.** The implem
252d0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  entation is not 
252e0 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76  required to prov
252f0 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66  ided versions of
25300 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e   these.** routin
25310 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79  es that actually
25320 20 77 6f 72 6b 2e 0a 2a 2a 20 49 66 20 74 68 65   work..** If the
25330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25340 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
25350 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73   working.** vers
25360 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f  ions of these ro
25370 75 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c  utines, it shoul
25380 64 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69  d at least provi
25390 64 65 20 73 74 75 62 73 0a 2a 2a 20 74 68 61 74  de stubs.** that
253a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
253b0 72 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20  rue so that one 
253c0 64 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75  does not get spu
253d0 72 69 6f 75 73 0a 2a 2a 20 61 73 73 65 72 74 69  rious.** asserti
253e0 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a  on failures..**.
253f0 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65  ** If the argume
25400 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  nt to sqlite3_mu
25410 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20 61 20  tex_held() is a 
25420 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25430 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  n.** the routine
25440 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 31   should return 1
25450 2e 20 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f  .  This seems co
25460 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20  unter-intuitive 
25470 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79  since.** clearly
25480 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f   the mutex canno
25490 74 20 62 65 20 68 65 6c 64 20 69 66 20 69 74 20  t be held if it 
254a0 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20  does not exist. 
254b0 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20   But the.** the 
254c0 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78  reason the mutex
254d0 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
254e0 69 73 20 62 65 63 61 75 73 65 20 74 68 65 20 62  is because the b
254f0 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75  uild is not.** u
25500 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41  sing mutexes.  A
25510 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e  nd we do not wan
25520 74 20 74 68 65 20 61 73 73 65 72 74 28 29 20 63  t the assert() c
25530 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
25540 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
25550 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f  _mutex_held() to
25560 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d   fail, so a non-
25570 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a  zero return is.*
25580 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  * the appropriat
25590 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20  e thing to do.  
255a0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
255b0 78 5f 6e 6f 74 68 65 6c 64 28 29 20 0a 2a 2a 20  x_notheld() .** 
255c0 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64  interface should
255d0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77   also return 1 w
255e0 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c  hen given a NULL
255f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69 6e 74   pointer..*/.int
25600 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
25610 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
25620 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  x*);.int sqlite3
25630 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73  _mutex_notheld(s
25640 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
25650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25660 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a   Mutex Types.**.
25670 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
25680 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69  mutex_alloc()] i
25690 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61  nterface takes a
256a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
256b0 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65  .** which is one
256c0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
256d0 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2f 0a  r constants..*/.
256e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
256f0 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20  UTEX_FAST       
25700 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
25710 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
25720 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a  URSIVE        1.
25730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25740 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
25750 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  ER    2.#define 
25760 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
25770 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20  TIC_MEM       3 
25780 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   /* sqlite3_mall
25790 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oc() */.#define 
257a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
257b0 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20  TIC_MEM2      4 
257c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65   /* sqlite3_rele
257d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 2a 2f 0a  ase_memory() */.
257e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
257f0 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
25800 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69        5  /* sqli
25810 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a  te3_random() */.
25820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
25830 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 20  UTEX_STATIC_LRU 
25840 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75 20        6  /* lru 
25850 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  page list */../*
25860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
25870 77 2d 4c 65 76 65 6c 20 43 6f 6e 74 72 6f 6c 20  w-Level Control 
25880 4f 66 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  Of Database File
25890 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
258a0 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
258b0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d  l()] interface m
258c0 61 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61  akes a direct ca
258d0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69  ll to the.** xFi
258e0 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
258f0 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
25900 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
25910 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a  ject associated.
25920 2a 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ** with a partic
25930 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64  ular database id
25940 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
25950 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
25960 20 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66    The.** name of
25970 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
25980 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
25990 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ed to the databa
259a0 73 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20  se by the.** <a 
259b0 68 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63  href="lang_attac
259c0 68 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f  h.html">ATTACH</
259d0 61 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74  a> SQL command t
259e0 68 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a  hat opened the.*
259f0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 54 6f 20  * database.  To 
25a00 63 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e  control the main
25a10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
25a20 75 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61  use the name "ma
25a30 69 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c  in".** or a NULL
25a40 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 74   pointer.  The t
25a50 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
25a60 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
25a70 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72  is routine.** ar
25a80 65 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c  e passed directl
25a90 79 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  y through to the
25aa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
25ab0 64 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a  d parameters of.
25ac0 2a 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** the xFileCont
25ad0 72 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 54 68 65  rol method.  The
25ae0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
25af0 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
25b00 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f  l.** method beco
25b10 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  mes the return v
25b20 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
25b30 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tine..**.** If t
25b40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25b50 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f  ter (zDbName) do
25b60 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65  es not match the
25b70 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   name of any.** 
25b80 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69  open database fi
25b90 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  le, then SQLITE_
25ba0 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65  ERROR is returne
25bb0 64 2e 20 20 54 68 69 73 20 65 72 72 6f 72 0a 2a  d.  This error.*
25bc0 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72 65  * code is not re
25bd0 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69 6c  membered and wil
25be0 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c 65  l not be recalle
25bf0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
25c00 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20 5b  rcode()].** or [
25c10 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
25c20 5d 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  ].  The underlyi
25c30 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ng xFileControl 
25c40 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a 20  method might.** 
25c50 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c 49  also return SQLI
25c60 54 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72 65  TE_ERROR.  There
25c70 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64 69   is no way to di
25c80 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65 65  stinguish betwee
25c90 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65 63  n.** an incorrec
25ca0 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61 6e  t zDbName and an
25cb0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72 65   SQLITE_ERROR re
25cc0 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75 6e  turn from the un
25cd0 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69 6c  derlying.** xFil
25ce0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
25cf0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25d00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
25d10 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
25d20 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
25d30 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
25d40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
25d50 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
25d60 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 55 6e 64 6f  d*);../*.** Undo
25d70 20 74 68 65 20 68 61 63 6b 20 74 68 61 74 20 63   the hack that c
25d80 6f 6e 76 65 72 74 73 20 66 6c 6f 61 74 69 6e 67  onverts floating
25d90 20 70 6f 69 6e 74 20 74 79 70 65 73 20 74 6f 20   point types to 
25da0 69 6e 74 65 67 65 72 20 66 6f 72 0a 2a 2a 20 62  integer for.** b
25db0 75 69 6c 64 73 20 6f 6e 20 70 72 6f 63 65 73 73  uilds on process
25dc0 6f 72 73 20 77 69 74 68 6f 75 74 20 66 6c 6f 61  ors without floa
25dd0 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
25de0 72 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  rt..*/.#ifdef SQ
25df0 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
25e00 4e 47 5f 50 4f 49 4e 54 0a 23 20 75 6e 64 65 66  NG_POINT.# undef
25e10 20 64 6f 75 62 6c 65 0a 23 65 6e 64 69 66 0a 0a   double.#endif..
25e20 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
25e30 75 73 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20  us.}  /* End of 
25e40 74 68 65 20 27 65 78 74 65 72 6e 20 22 43 22 27  the 'extern "C"'
25e50 20 62 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66   block */.#endif
25e60 0a 23 65 6e 64 69 66 0a                          .#endif.